diff --git a/.env.example b/.env.example
index eec52d87..bf0b0d47 100644
--- a/.env.example
+++ b/.env.example
@@ -9,3 +9,9 @@ VITE_GATEWAY_TOKEN=
 
 # Mock 模式（设为 true 可不连接真实 Gateway 进行开发）
 # VITE_MOCK=true
+
+# --- 运营商引导配置（可选）---
+# 运营商引导包 URL（用于从框架层加载 projection bootstrap 数据）
+# 支持 HTTP/HTTPS URL 或本地相对路径
+# VITE_PROJECTION_BOOTSTRAP_URL=https://example.com/projection-bootstrap.json
+# VITE_PROJECTION_BOOTSTRAP_PATH=/bootstrap/projection-packet.json
diff --git a/README.md b/README.md
index 83cf87dd..4329e85b 100644
--- a/README.md
+++ b/README.md
@@ -203,6 +203,36 @@ VITE_MOCK=true pnpm dev
 
 This uses simulated Agent data for UI development.
 
+In the current bootstrap, mock mode also loads the framework-generated projection packet sample and seeds the office scene plus the first-batch projection panels from that packet. This is still a mock/dev path only; it does not change the live Gateway contract.
+
+### Operator-Facing Projection Bootstrap (Real Gateway + bootstrap feed)
+
+A controlled non-mock/operator path is also available when you want Office to connect to the **real Gateway** while still seeding the first projection panels from a framework-generated packet.
+
+1. Generate or copy a packet such as:
+   - `/home/ubuntu/projects/_department/work/openclaw-office-projection-feed-bootstrap-20260325/fixtures/openclaw_office_projection_packet_v0.json`
+2. Serve it from the Office app origin, for example:
+
+```bash
+mkdir -p public/bootstrap
+cp /path/to/openclaw_office_projection_packet_v0.json public/bootstrap/projection-packet.json
+```
+
+3. Start Office against the real Gateway and point the operator bootstrap to that URL:
+
+```bash
+VITE_GATEWAY_URL=ws://127.0.0.1:18789 \
+VITE_GATEWAY_TOKEN=<your-token> \
+VITE_PROJECTION_BOOTSTRAP_URL=/bootstrap/projection-packet.json \
+pnpm dev
+```
+
+Behavior boundary:
+- the real Gateway connection path remains intact
+- bootstrap loading is optional and guarded by env vars
+- this does **not** introduce a new live Gateway protocol message
+- this supports operator-facing rollout progress, but does **not** by itself claim upstream merge
+
 ---
 
 ## Project Structure
diff --git a/src/components/layout/Sidebar.tsx b/src/components/layout/Sidebar.tsx
index 9ed61546..ae741ab0 100644
--- a/src/components/layout/Sidebar.tsx
+++ b/src/components/layout/Sidebar.tsx
@@ -3,6 +3,7 @@ import { useTranslation } from "react-i18next";
 import { AgentDetailPanel } from "@/components/panels/AgentDetailPanel";
 import { EventTimeline } from "@/components/panels/EventTimeline";
 import { MetricsPanel } from "@/components/panels/MetricsPanel";
+import { ProjectionBootstrapPanel } from "@/components/panels/ProjectionBootstrapPanel";
 import { SubAgentPanel } from "@/components/panels/SubAgentPanel";
 import { CollapsibleSection } from "@/components/shared/CollapsibleSection";
 import { SvgAvatar } from "@/components/shared/SvgAvatar";
@@ -17,6 +18,7 @@ export function Sidebar() {
   const { t } = useTranslation("layout");
   const agents = useOfficeStore((s) => s.agents);
   const selectedAgentId = useOfficeStore((s) => s.selectedAgentId);
+  const projectionPanels = useOfficeStore((s) => s.projectionPanels);
   const selectAgent = useOfficeStore((s) => s.selectAgent);
   const collapsed = useOfficeStore((s) => s.sidebarCollapsed);
   const setSidebarCollapsed = useOfficeStore((s) => s.setSidebarCollapsed);
@@ -76,6 +78,7 @@ export function Sidebar() {
   const subAgentsSection = getSection("subAgents");
   const detailSection = getSection("detail");
   const timelineSection = getSection("timeline");
+  const projectionSection = getSection("projectionBootstrap");
 
   return (
     <aside className="flex w-80 flex-col border-l border-gray-200 bg-white dark:border-gray-700 dark:bg-gray-900">
@@ -103,10 +106,26 @@ export function Sidebar() {
         onHeightChange={(h) => setSectionHeight("metrics", h)}
         minHeight={120}
         maxHeight={400}
-      >
+        >
         <MetricsPanel />
       </CollapsibleSection>
 
+      {projectionPanels.length > 0 && (
+        <CollapsibleSection
+          id="projectionBootstrap"
+          title={t("sidebar.projectionBootstrap")}
+          collapsed={projectionSection.collapsed}
+          onToggle={() => toggleSection("projectionBootstrap")}
+          height={projectionSection.height}
+          onHeightChange={(h) => setSectionHeight("projectionBootstrap", h)}
+          minHeight={180}
+          maxHeight={520}
+          badge={projectionPanels.length}
+        >
+          <ProjectionBootstrapPanel />
+        </CollapsibleSection>
+      )}
+
       {/* Agent list — primary section, takes remaining space */}
       <CollapsibleSection
         id="agents"
diff --git a/src/components/layout/__tests__/Sidebar.test.tsx b/src/components/layout/__tests__/Sidebar.test.tsx
index 91b446f2..f04e9c80 100644
--- a/src/components/layout/__tests__/Sidebar.test.tsx
+++ b/src/components/layout/__tests__/Sidebar.test.tsx
@@ -1,6 +1,6 @@
 import { render, screen, fireEvent, within } from "@testing-library/react";
 import { MemoryRouter } from "react-router-dom";
-import { describe, it, expect, beforeEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { Sidebar } from "@/components/layout/Sidebar";
 import i18n from "@/i18n/test-setup";
 import { useOfficeStore } from "@/store/office-store";
@@ -22,6 +22,7 @@ describe("Sidebar", () => {
       selectedAgentId: null,
       sidebarCollapsed: false,
       eventHistory: [],
+      projectionPanels: [],
       globalMetrics: {
         activeAgents: 0,
         totalAgents: 0,
@@ -38,6 +39,28 @@ describe("Sidebar", () => {
     setupAgents();
   });
 
+  afterEach(() => {
+    useOfficeStore.setState({
+      agents: new Map(),
+      selectedAgentId: null,
+      sidebarCollapsed: false,
+      eventHistory: [],
+      projectionPanels: [],
+      globalMetrics: {
+        activeAgents: 0,
+        totalAgents: 0,
+        totalTokens: 0,
+        tokenRate: 0,
+        collaborationHeat: 0,
+      },
+      links: [],
+      connectionStatus: "disconnected",
+      connectionError: null,
+      runIdMap: new Map(),
+      sessionKeyMap: new Map(),
+    });
+  });
+
   it("renders all agents", () => {
     render(<MemoryRouter><Sidebar /></MemoryRouter>);
     expect(screen.getByText("Coder")).toBeInTheDocument();
@@ -73,4 +96,52 @@ describe("Sidebar", () => {
     expect(screen.getAllByText("Coder").length).toBeGreaterThan(0);
     expect(screen.queryByText("Reviewer")).not.toBeInTheDocument();
   });
+
+  it("renders projection bootstrap panels when seeded", () => {
+    useOfficeStore.getState().applyProjectionBootstrap({
+      schemaVersion: "openclaw-office-projection-packet.v0",
+      generatedAt: "2026-03-25T07:15:13Z",
+      sources: {},
+      officeProjection: {
+        mode: "framework-bootstrap/mock-seed-ready",
+        runtimeBoundary: {
+          contextEngineSlot: "legacy",
+          projectionContextEngineRolloutGate: "unchanged",
+          notes: [],
+        },
+        scene: {
+          agents: [],
+          links: [],
+          eventHistory: [],
+          globalMetrics: {
+            activeAgents: 0,
+            totalAgents: 0,
+            totalTokens: 0,
+            tokenRate: 0,
+            collaborationHeat: 0,
+          },
+        },
+        panels: {
+          decisionDrift: {
+            panelId: "decision-drift",
+            title: "Decision drift",
+            severity: "warn",
+            summary: { count: 1 },
+            items: [
+              {
+                kind: "deterministic-example",
+                title: "Pointer cache tries to override live board focus",
+                caseId: "live_projection_pointer_override",
+              },
+            ],
+          },
+        },
+      },
+    });
+
+    render(<MemoryRouter><Sidebar /></MemoryRouter>);
+    expect(screen.getByText(t("layout:sidebar.projectionBootstrap"))).toBeInTheDocument();
+    expect(screen.getByText("Decision drift")).toBeInTheDocument();
+    expect(screen.getByText("Pointer cache tries to override live board focus")).toBeInTheDocument();
+  });
 });
diff --git a/src/components/panels/ProjectionBootstrapPanel.tsx b/src/components/panels/ProjectionBootstrapPanel.tsx
new file mode 100644
index 00000000..f0c944a4
--- /dev/null
+++ b/src/components/panels/ProjectionBootstrapPanel.tsx
@@ -0,0 +1,168 @@
+import { useTranslation } from "react-i18next";
+import type { ProjectionPanel, ProjectionPanelItem } from "@/gateway/types";
+import { useOfficeStore } from "@/store/office-store";
+
+export function ProjectionBootstrapPanel() {
+  const { t } = useTranslation("panels");
+  const panels = useOfficeStore((s) => s.projectionPanels);
+
+  if (panels.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="space-y-2 px-2 py-2">
+      {panels.map((panel) => (
+        <ProjectionPanelCard key={panel.panelId} panel={panel} t={t} />
+      ))}
+    </div>
+  );
+}
+
+function ProjectionPanelCard({
+  panel,
+  t,
+}: {
+  panel: ProjectionPanel;
+  t: (key: string, opts?: { count?: number }) => string;
+}) {
+  const severityClass = severityClasses[panel.severity];
+  const summaryEntries = Object.entries(panel.summary);
+
+  return (
+    <article className="rounded-lg border border-gray-200 bg-white px-2 py-2 shadow-sm dark:border-gray-700 dark:bg-gray-900">
+      <div className="flex items-center justify-between gap-2">
+        <h4 className="min-w-0 truncate text-xs font-semibold text-gray-800 dark:text-gray-100">
+          {panel.title}
+        </h4>
+        <span
+          className={`shrink-0 rounded-full px-2 py-0.5 text-[10px] font-medium ${severityClass}`}
+        >
+          {t(`projectionBootstrap.severities.${panel.severity}`)}
+        </span>
+      </div>
+
+      <div className="mt-1 flex flex-wrap gap-1">
+        {summaryEntries.map(([key, value]) => (
+          <span
+            key={key}
+            className="rounded bg-gray-100 px-1.5 py-0.5 text-[10px] text-gray-600 dark:bg-gray-800 dark:text-gray-300"
+          >
+            {key}: {String(value)}
+          </span>
+        ))}
+      </div>
+
+      <div className="mt-2 space-y-1">
+        {panel.items.length > 0 ? (
+          panel.items.slice(0, 2).map((item) => (
+            <ProjectionPanelItemRow key={item.caseId ?? item.title} item={item} t={t} depth={0} />
+          ))
+        ) : (
+          <div className="rounded bg-gray-50 px-2 py-1 text-[10px] text-gray-500 dark:bg-gray-800 dark:text-gray-400">
+            {panel.emptyState ?? t("projectionBootstrap.noItems")}
+          </div>
+        )}
+        {panel.items.length > 2 && (
+          <div className="pt-1 text-[10px] text-gray-400 dark:text-gray-500">
+            {t("projectionBootstrap.moreItems", { count: panel.items.length - 2 })}
+          </div>
+        )}
+      </div>
+    </article>
+  );
+}
+
+function ProjectionPanelItemRow({
+  item,
+  t,
+  depth,
+}: {
+  item: ProjectionPanelItem;
+  t: (key: string, opts?: { count?: number }) => string;
+  depth: number;
+}) {
+  const meta = buildItemMeta(item, t);
+  const detailTags = [
+    ...normalizeTags(item.driftTypes),
+    ...normalizeTags(item.detectedDriftTypes),
+  ];
+
+  return (
+    <div className={`rounded border border-gray-100 bg-gray-50 px-2 py-1 dark:border-gray-800 dark:bg-gray-800/70 ${depth > 0 ? "ml-2" : ""}`}>
+      <div className="text-[11px] font-medium text-gray-700 dark:text-gray-200">{item.title}</div>
+      {meta.length > 0 && (
+        <div className="mt-0.5 flex flex-wrap gap-x-2 gap-y-0.5 text-[10px] text-gray-500 dark:text-gray-400">
+          {meta.map((line) => (
+            <span key={line}>{line}</span>
+          ))}
+        </div>
+      )}
+      {detailTags.length > 0 && (
+        <div className="mt-1 flex flex-wrap gap-1">
+          {detailTags.map((tag) => (
+            <span
+              key={tag}
+              className="rounded-full bg-blue-50 px-1.5 py-0.5 text-[10px] text-blue-700 dark:bg-blue-950/60 dark:text-blue-300"
+            >
+              {tag}
+            </span>
+          ))}
+        </div>
+      )}
+      {item.driftCounts && Object.keys(item.driftCounts).length > 0 && (
+        <div className="mt-1 flex flex-wrap gap-1">
+          {Object.entries(item.driftCounts).map(([key, value]) => (
+            <span
+              key={key}
+              className="rounded bg-orange-50 px-1.5 py-0.5 text-[10px] text-orange-700 dark:bg-orange-950/60 dark:text-orange-300"
+            >
+              {key}: {value}
+            </span>
+          ))}
+        </div>
+      )}
+      {item.chainLabels && item.chainLabels.length > 0 && (
+        <div className="mt-1 text-[10px] text-gray-500 dark:text-gray-400">
+          {item.chainLabels.join(" → ")}
+        </div>
+      )}
+      {item.examples && item.examples.length > 0 && (
+        <div className="mt-1 space-y-1">
+          {item.examples.slice(0, 2).map((example) => (
+            <ProjectionPanelItemRow
+              key={example.caseId ?? example.title}
+              item={example}
+              t={t}
+              depth={depth + 1}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function buildItemMeta(item: ProjectionPanelItem, t: (key: string, opts?: { count?: number }) => string): string[] {
+  const lines: string[] = [];
+  if (item.caseId) lines.push(`${t("projectionBootstrap.meta.caseId")}: ${item.caseId}`);
+  if (item.sourceSession) lines.push(`${t("projectionBootstrap.meta.sourceSession")}: ${item.sourceSession}`);
+  if (item.taskId) lines.push(`${t("projectionBootstrap.meta.taskId")}: ${item.taskId}`);
+  if (item.owner) lines.push(`${t("projectionBootstrap.meta.owner")}: ${item.owner}`);
+  if (item.state) lines.push(`${t("projectionBootstrap.meta.state")}: ${item.state}`);
+  if (item.reason) lines.push(`${t("projectionBootstrap.meta.reason")}: ${item.reason}`);
+  if (item.path) lines.push(`${t("projectionBootstrap.meta.path")}: ${item.path}`);
+  return lines;
+}
+
+function normalizeTags(tags?: string[]): string[] {
+  return tags?.filter(Boolean) ?? [];
+}
+
+const severityClasses: Record<ProjectionPanel["severity"], string> = {
+  info: "bg-slate-100 text-slate-700 dark:bg-slate-800 dark:text-slate-300",
+  warn: "bg-amber-100 text-amber-800 dark:bg-amber-950/60 dark:text-amber-300",
+  error: "bg-red-100 text-red-700 dark:bg-red-950/60 dark:text-red-300",
+  success: "bg-emerald-100 text-emerald-700 dark:bg-emerald-950/60 dark:text-emerald-300",
+};
+
diff --git a/src/gateway/__tests__/projection-bootstrap-fetcher.test.ts b/src/gateway/__tests__/projection-bootstrap-fetcher.test.ts
new file mode 100644
index 00000000..f40bd191
--- /dev/null
+++ b/src/gateway/__tests__/projection-bootstrap-fetcher.test.ts
@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  fetchProjectionBootstrap,
+  isOperatorBootstrapConfigured,
+  validatePacket,
+} from "@/gateway/projection-bootstrap-fetcher";
+
+const VALID_PACKET = {
+  schemaVersion: "openclaw-office-projection-packet.v0",
+  generatedAt: "2026-03-27T00:00:00Z",
+  officeProjection: {
+    scene: {
+      agents: [],
+      links: [],
+    },
+    eventHistory: [],
+    panelData: {},
+  },
+};
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+});
+
+describe("projection-bootstrap-fetcher", () => {
+  it("returns null when operator bootstrap is not configured", async () => {
+    expect(isOperatorBootstrapConfigured()).toBe(false);
+    await expect(fetchProjectionBootstrap()).resolves.toBeNull();
+  });
+
+  it("fetches and validates a bootstrap packet from URL", async () => {
+    vi.stubEnv("VITE_PROJECTION_BOOTSTRAP_URL", "/bootstrap/projection-packet.json");
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => VALID_PACKET,
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    expect(isOperatorBootstrapConfigured()).toBe(true);
+    await expect(fetchProjectionBootstrap()).resolves.toEqual(VALID_PACKET);
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/bootstrap/projection-packet.json",
+      expect.objectContaining({ method: "GET" }),
+    );
+  });
+
+  it("rejects invalid packets", () => {
+    expect(() => validatePacket({ generatedAt: "2026-03-27T00:00:00Z" })).toThrow(
+      /schemaVersion/,
+    );
+  });
+});
diff --git a/src/gateway/projection-bootstrap-fetcher.ts b/src/gateway/projection-bootstrap-fetcher.ts
new file mode 100644
index 00000000..94e2058e
--- /dev/null
+++ b/src/gateway/projection-bootstrap-fetcher.ts
@@ -0,0 +1,125 @@
+/**
+ * Projection Bootstrap Fetcher
+ *
+ * Provides an operator-facing, non-mock path for loading projection bootstrap packets
+ * from a configurable URL or local file. Works alongside the real Gateway connection.
+ *
+ * Configuration via environment variables:
+ * - VITE_PROJECTION_BOOTSTRAP_URL: URL to fetch the bootstrap packet (JSON)
+ * - VITE_PROJECTION_BOOTSTRAP_PATH: Alternative - local file path (for dev)
+ *
+ * Guarded behavior: If neither is configured, does nothing.
+ */
+
+import type { ProjectionBootstrapPacket } from "@/gateway/types";
+
+/**
+ * Fetch projection bootstrap packet from configured source.
+ * Returns null if no source is configured or if fetch fails.
+ */
+export async function fetchProjectionBootstrap(): Promise<ProjectionBootstrapPacket | null> {
+  const url = import.meta.env.VITE_PROJECTION_BOOTSTRAP_URL;
+  const path = import.meta.env.VITE_PROJECTION_BOOTSTRAP_PATH;
+
+  // No source configured
+  if (!url && !path) {
+    return null;
+  }
+
+  try {
+    if (url) {
+      return await fetchFromUrl(url);
+    }
+    if (path) {
+      return await fetchFromPath(path);
+    }
+  } catch (error) {
+    console.warn(
+      "[projection-bootstrap-fetcher] Failed to load bootstrap packet:",
+      error instanceof Error ? error.message : String(error),
+    );
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Fetch bootstrap packet from a remote URL.
+ */
+async function fetchFromUrl(url: string): Promise<ProjectionBootstrapPacket | null> {
+  const response = await fetch(url, {
+    method: "GET",
+    headers: {
+      "Accept": "application/json",
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+
+  const packet = await response.json();
+  return validatePacket(packet);
+}
+
+/**
+ * Fetch bootstrap packet from a local file path.
+ * Note: This only works in dev mode with Vite's file access.
+ */
+async function fetchFromPath(path: string): Promise<ProjectionBootstrapPacket | null> {
+  const response = await fetch(path);
+
+  if (!response.ok) {
+    throw new Error(`Failed to load ${path}: ${response.statusText}`);
+  }
+
+  const packet = await response.json();
+  return validatePacket(packet);
+}
+
+/**
+ * Validate that the loaded packet has the expected structure.
+ * Returns the packet if valid, throws if invalid.
+ * Exported for testing purposes.
+ */
+export function validatePacket(packet: unknown): ProjectionBootstrapPacket {
+  if (!packet || typeof packet !== "object") {
+    throw new Error("Invalid packet: not an object");
+  }
+
+  const p = packet as Record<string, unknown>;
+
+  // Required fields
+  if (typeof p.schemaVersion !== "string") {
+    throw new Error("Invalid packet: missing or invalid schemaVersion");
+  }
+  if (typeof p.generatedAt !== "string") {
+    throw new Error("Invalid packet: missing or invalid generatedAt");
+  }
+  if (!p.officeProjection || typeof p.officeProjection !== "object") {
+    throw new Error("Invalid packet: missing officeProjection");
+  }
+
+  const projection = p.officeProjection as Record<string, unknown>;
+  if (!projection.scene || typeof projection.scene !== "object") {
+    throw new Error("Invalid packet: missing officeProjection.scene");
+  }
+
+  const scene = projection.scene as Record<string, unknown>;
+  if (!Array.isArray(scene.agents)) {
+    throw new Error("Invalid packet: missing officeProjection.scene.agents");
+  }
+
+  return packet as ProjectionBootstrapPacket;
+}
+
+/**
+ * Check if operator bootstrap is configured.
+ */
+export function isOperatorBootstrapConfigured(): boolean {
+  return Boolean(
+    import.meta.env.VITE_PROJECTION_BOOTSTRAP_URL ||
+    import.meta.env.VITE_PROJECTION_BOOTSTRAP_PATH,
+  );
+}
diff --git a/src/gateway/types.ts b/src/gateway/types.ts
index 85003d2f..6071f78a 100644
--- a/src/gateway/types.ts
+++ b/src/gateway/types.ts
@@ -258,6 +258,64 @@ export interface TokenSnapshot {
   byAgent: Record<string, number>;
 }
 
+export interface ProjectionBootstrapAgent extends VisualAgent {
+  meta?: Record<string, unknown>;
+}
+
+export interface ProjectionPanelItem {
+  kind: string;
+  title: string;
+  caseId?: string;
+  sourceSession?: string;
+  driftTypes?: string[];
+  detectedDriftTypes?: string[];
+  driftCounts?: Record<string, number>;
+  examples?: ProjectionPanelItem[];
+  taskId?: string;
+  slug?: string;
+  chain?: string[];
+  chainLabels?: string[];
+  owner?: string;
+  state?: string;
+  reason?: string;
+  path?: string;
+}
+
+export interface ProjectionPanel {
+  panelId: string;
+  title: string;
+  severity: "info" | "warn" | "error" | "success";
+  summary: Record<string, number | string>;
+  items: ProjectionPanelItem[];
+  emptyState?: string | null;
+}
+
+export interface ProjectionRuntimeBoundary {
+  contextEngineSlot: "legacy" | "projection";
+  projectionContextEngineRolloutGate: string;
+  notes: string[];
+}
+
+export interface ProjectionBootstrapScene {
+  agents: ProjectionBootstrapAgent[];
+  links: CollaborationLink[];
+  eventHistory: EventHistoryItem[];
+  globalMetrics: GlobalMetrics;
+}
+
+export interface ProjectionBootstrapPacket {
+  schemaVersion: string;
+  generatedAt: string;
+  sources: Record<string, string>;
+  officeProjection: {
+    mode: string;
+    runtimeBoundary: ProjectionRuntimeBoundary;
+    scene: ProjectionBootstrapScene;
+    panels: Record<string, ProjectionPanel>;
+    coverage?: Record<string, unknown>;
+  };
+}
+
 export interface OfficeStore {
   agents: Map<string, VisualAgent>;
   links: CollaborationLink[];
@@ -268,6 +326,7 @@ export interface OfficeStore {
   eventHistory: EventHistoryItem[];
   sidebarCollapsed: boolean;
   lastSessionsSnapshot: SessionSnapshot | null;
+  projectionPanels: ProjectionPanel[];
   theme: ThemeMode;
   operatorScopes: string[];
   tokenHistory: TokenSnapshot[];
@@ -313,6 +372,7 @@ export interface OfficeStore {
 
   // Sessions 轮询
   setSessionsSnapshot: (snapshot: SessionSnapshot) => void;
+  applyProjectionBootstrap: (packet: ProjectionBootstrapPacket) => void;
 
   // 事件处理
   processAgentEvent: (event: AgentEventPayload) => void;
diff --git a/src/hooks/useGatewayConnection.ts b/src/hooks/useGatewayConnection.ts
index 826abf0f..56acee59 100644
--- a/src/hooks/useGatewayConnection.ts
+++ b/src/hooks/useGatewayConnection.ts
@@ -1,5 +1,6 @@
 import { useEffect, useRef } from "react";
 import { initAdapter, isMockMode } from "@/gateway/adapter-provider";
+import { fetchProjectionBootstrap, isOperatorBootstrapConfigured } from "@/gateway/projection-bootstrap-fetcher";
 import { GatewayRpcClient } from "@/gateway/rpc-client";
 import type {
   AgentEventPayload,
@@ -7,9 +8,11 @@ import type {
   AgentsListResponse,
   GatewayEventFrame,
   HealthSnapshot,
+  ProjectionBootstrapPacket,
 } from "@/gateway/types";
 import { GatewayWsClient } from "@/gateway/ws-client";
 import { EventThrottle } from "@/lib/event-throttle";
+import { MOCK_PROJECTION_BOOTSTRAP } from "@/mock/projection-bootstrap";
 import { useOfficeStore } from "@/store/office-store";
 import { useSubAgentPoller } from "./useSubAgentPoller";
 import { useUsagePoller } from "./useUsagePoller";
@@ -27,6 +30,7 @@ export function useGatewayConnection({ url, token }: UseGatewayConnectionOptions
   const setConnectionStatus = useOfficeStore((s) => s.setConnectionStatus);
   const initAgents = useOfficeStore((s) => s.initAgents);
   const syncMainAgents = useOfficeStore((s) => s.syncMainAgents);
+  const applyProjectionBootstrap = useOfficeStore((s) => s.applyProjectionBootstrap);
   const processAgentEvent = useOfficeStore((s) => s.processAgentEvent);
   const setOperatorScopes = useOfficeStore((s) => s.setOperatorScopes);
   const setMaxSubAgents = useOfficeStore((s) => s.setMaxSubAgents);
@@ -47,6 +51,8 @@ export function useGatewayConnection({ url, token }: UseGatewayConnectionOptions
           }
         });
 
+        applyProjectionBootstrap(MOCK_PROJECTION_BOOTSTRAP);
+
         const config = await adapter.configGet();
         const cfg = config.config as Record<string, unknown>;
         const agentsCfg = cfg.agents as Record<string, unknown> | undefined;
@@ -64,9 +70,8 @@ export function useGatewayConnection({ url, token }: UseGatewayConnectionOptions
           });
         }
 
-        const agentList = await adapter.agentsList() as AgentsListResponse;
+        const agentList = (await adapter.agentsList()) as AgentsListResponse;
         cacheAgentNames(agentList.agents);
-        initAgents(agentList.agents);
         setOperatorScopes(["operator.admin", "operator.read"]);
         setConnectionStatus("connected");
       });
@@ -123,6 +128,12 @@ export function useGatewayConnection({ url, token }: UseGatewayConnectionOptions
 
     ws.connect(url, token);
 
+    // Operator-facing bootstrap: load projection packet from configured URL/path
+    // This runs in parallel with the real Gateway connection, non-mock mode only.
+    if (!isMockMode() && isOperatorBootstrapConfigured()) {
+      void loadOperatorBootstrap(applyProjectionBootstrap);
+    }
+
     return () => {
       throttle.destroy();
       ws.disconnect();
@@ -137,6 +148,7 @@ export function useGatewayConnection({ url, token }: UseGatewayConnectionOptions
     initAgents,
     syncMainAgents,
     processAgentEvent,
+    applyProjectionBootstrap,
     setOperatorScopes,
     setMaxSubAgents,
     setAgentToAgentConfig,
@@ -233,3 +245,23 @@ async function fetchGatewayConfig(
     // config.get not available; keep defaults
   }
 }
+
+/**
+ * Load operator-facing projection bootstrap packet.
+ * Called once after Gateway connection in non-mock mode.
+ */
+async function loadOperatorBootstrap(
+  applyBootstrap: (packet: ProjectionBootstrapPacket) => void,
+): Promise<void> {
+  try {
+    const packet = await fetchProjectionBootstrap();
+    if (packet) {
+      applyBootstrap(packet);
+    }
+  } catch (error) {
+    console.warn(
+      "[useGatewayConnection] Failed to load operator bootstrap:",
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+}
diff --git a/src/i18n/locales/en/layout.json b/src/i18n/locales/en/layout.json
index c7ec91d6..fa8eebdb 100644
--- a/src/i18n/locales/en/layout.json
+++ b/src/i18n/locales/en/layout.json
@@ -35,6 +35,7 @@
     "expandSidebar": "Expand sidebar",
     "collapseSidebar": "Collapse sidebar",
     "metricsTitle": "Overview / Trends",
+    "projectionBootstrap": "Projection bootstrap",
     "agentList": "Agent List",
     "subAgents": "Sub-Agents",
     "agentDetail": "Agent Detail",
diff --git a/src/i18n/locales/en/panels.json b/src/i18n/locales/en/panels.json
index bfc8c56c..1e5fd7d7 100644
--- a/src/i18n/locales/en/panels.json
+++ b/src/i18n/locales/en/panels.json
@@ -17,6 +17,25 @@
     "deselect": "Deselect",
     "toolCallHistory": "Tool Call History"
   },
+  "projectionBootstrap": {
+    "moreItems": "{{count}} more item(s)",
+    "noItems": "No bootstrap items",
+    "severities": {
+      "info": "Info",
+      "warn": "Warn",
+      "error": "Error",
+      "success": "Success"
+    },
+    "meta": {
+      "caseId": "Case",
+      "sourceSession": "Session",
+      "taskId": "Task",
+      "owner": "Owner",
+      "state": "State",
+      "reason": "Reason",
+      "path": "Path"
+    }
+  },
   "eventTimeline": {
     "newEvents": "New events ↓"
   },
diff --git a/src/i18n/locales/zh/layout.json b/src/i18n/locales/zh/layout.json
index 5099ae0d..29f0b8bf 100644
--- a/src/i18n/locales/zh/layout.json
+++ b/src/i18n/locales/zh/layout.json
@@ -35,6 +35,7 @@
     "expandSidebar": "展开侧栏",
     "collapseSidebar": "收起侧栏",
     "metricsTitle": "概览 / 趋势",
+    "projectionBootstrap": "投影引导",
     "agentList": "智能体 列表",
     "subAgents": "子智能体",
     "agentDetail": "智能体 详情",
diff --git a/src/i18n/locales/zh/panels.json b/src/i18n/locales/zh/panels.json
index ea8c690c..09d3b5f4 100644
--- a/src/i18n/locales/zh/panels.json
+++ b/src/i18n/locales/zh/panels.json
@@ -17,6 +17,25 @@
     "deselect": "取消选择",
     "toolCallHistory": "工具调用历史"
   },
+  "projectionBootstrap": {
+    "moreItems": "还有 {{count}} 项",
+    "noItems": "没有引导数据",
+    "severities": {
+      "info": "信息",
+      "warn": "警告",
+      "error": "错误",
+      "success": "成功"
+    },
+    "meta": {
+      "caseId": "案例",
+      "sourceSession": "会话",
+      "taskId": "任务",
+      "owner": "负责人",
+      "state": "状态",
+      "reason": "原因",
+      "path": "路径"
+    }
+  },
   "eventTimeline": {
     "newEvents": "新事件 ↓"
   },
diff --git a/src/mock/projection-bootstrap.ts b/src/mock/projection-bootstrap.ts
new file mode 100644
index 00000000..fadb52dd
--- /dev/null
+++ b/src/mock/projection-bootstrap.ts
@@ -0,0 +1,381 @@
+import type { ProjectionBootstrapPacket } from "@/gateway/types";
+
+export const MOCK_PROJECTION_BOOTSTRAP = {
+  schemaVersion: "openclaw-office-projection-packet.v0",
+  generatedAt: "2026-03-25T07:15:13Z",
+  sources: {
+    coreArchitecturePath: "/home/ubuntu/.openclaw/workspace/openclaw_todo/agent_framework/CORE_ARCHITECTURE.md",
+    todoPath:
+      "/home/ubuntu/.openclaw/workspace/openclaw_todo/agent_framework/确定性会话记录与可重放框架_todolist.md",
+    liveBoardPath:
+      "/home/ubuntu/.openclaw/workspace-ceo/work/ceo-cadence-automation-20260323/COMPANY_LIVE_BOARD_20260324T071646Z.json",
+    eventSummaryPath:
+      "/home/ubuntu/.openclaw/workspace-ceo/work/ceo-cadence-automation-20260323/COMPANY_EVENT_SUMMARY_20260324T0642Z_from0623.json",
+    deterministicSuiteSummaryPath:
+      "/home/ubuntu/projects/_department/work/replay-trace-deterministic-first-scenario-suite-20260324/fixtures/deterministic_first_summary.json",
+    deterministicSuiteLiveReceiptPath:
+      "/home/ubuntu/projects/_department/work/replay-trace-deterministic-first-scenario-suite-20260324/fixtures/live_suite/live_suite.receipt.json",
+    recentRealReplayLiveReceiptPath:
+      "/home/ubuntu/projects/_department/work/replay-trace-replay-ci-full-closeout-20260324/fixtures_lock_enforced/live_suite/live_suite.receipt.json",
+    openclawOfficeReadme: "https://raw.githubusercontent.com/WW-AI-Lab/openclaw-office/main/README.md",
+    openclawOfficeTypes: "https://raw.githubusercontent.com/WW-AI-Lab/openclaw-office/main/src/gateway/types.ts",
+  },
+  officeProjection: {
+    mode: "framework-bootstrap/mock-seed-ready",
+    runtimeBoundary: {
+      contextEngineSlot: "legacy",
+      projectionContextEngineRolloutGate: "unchanged",
+      notes: [
+        "This packet is generated from projection/governance/replay artifacts only.",
+        "It does not change the live context engine slot or the rollout gate.",
+      ],
+    },
+    scene: {
+      agents: [
+        {
+          id: "main",
+          name: "main-agent",
+          status: "idle",
+          position: { x: 120, y: 110 },
+          currentTool: null,
+          speechBubble: null,
+          lastActiveAt: 1774422913000,
+          toolCallCount: 0,
+          toolCallHistory: [],
+          runId: null,
+          isSubAgent: false,
+          isPlaceholder: false,
+          parentAgentId: null,
+          childAgentIds: ["ceo-agent"],
+          zone: "desk",
+          originalPosition: null,
+          movement: null,
+          confirmed: true,
+          arrivedAtHotDeskAt: null,
+          pendingRetire: false,
+          meta: {
+            department: "executive-office",
+            boardFocusTaskId: null,
+            acceptedIdleCount: 0,
+          },
+        },
+        {
+          id: "ceo-agent",
+          name: "CEO-agent",
+          status: "thinking",
+          position: { x: 320, y: 110 },
+          currentTool: {
+            name: "projection_refresh",
+            args: { source: "company-live-board" },
+            startedAt: 1774422913000,
+          },
+          speechBubble: {
+            text: "1 accepted-but-idle task(s) need owner motion",
+            timestamp: 1774422913000,
+          },
+          lastActiveAt: 1774422913000,
+          toolCallCount: 1,
+          toolCallHistory: [{ name: "projection_refresh", timestamp: 1774422913000 }],
+          runId: null,
+          isSubAgent: false,
+          isPlaceholder: false,
+          parentAgentId: "main",
+          childAgentIds: ["engai-agent", "content-agent", "market-agent", "daily-agent"],
+          zone: "meeting",
+          originalPosition: null,
+          movement: null,
+          confirmed: true,
+          arrivedAtHotDeskAt: null,
+          pendingRetire: false,
+          meta: {
+            department: "executive-office",
+            boardFocusTaskId: null,
+            acceptedIdleCount: 0,
+          },
+        },
+        {
+          id: "engai-agent",
+          name: "engai-agent",
+          status: "idle",
+          position: { x: 160, y: 280 },
+          currentTool: null,
+          speechBubble: {
+            text: "Focus: mvp-bootstrap (accepted)",
+            timestamp: 1774422913000,
+          },
+          lastActiveAt: 1774422913000,
+          toolCallCount: 0,
+          toolCallHistory: [],
+          runId: null,
+          isSubAgent: true,
+          isPlaceholder: false,
+          parentAgentId: "ceo-agent",
+          childAgentIds: [],
+          zone: "desk",
+          originalPosition: null,
+          movement: null,
+          confirmed: true,
+          arrivedAtHotDeskAt: null,
+          pendingRetire: false,
+          meta: {
+            department: "engai",
+            boardFocusTaskId: "tsk_mvp_bootstrap",
+            acceptedIdleCount: 1,
+          },
+        },
+        {
+          id: "content-agent",
+          name: "content-agent",
+          status: "idle",
+          position: { x: 320, y: 280 },
+          currentTool: null,
+          speechBubble: null,
+          lastActiveAt: 1774422913000,
+          toolCallCount: 0,
+          toolCallHistory: [],
+          runId: null,
+          isSubAgent: true,
+          isPlaceholder: false,
+          parentAgentId: "ceo-agent",
+          childAgentIds: [],
+          zone: "desk",
+          originalPosition: null,
+          movement: null,
+          confirmed: true,
+          arrivedAtHotDeskAt: null,
+          pendingRetire: false,
+          meta: {
+            department: "content",
+            boardFocusTaskId: null,
+            acceptedIdleCount: 0,
+          },
+        },
+        {
+          id: "market-agent",
+          name: "market-agent",
+          status: "idle",
+          position: { x: 480, y: 280 },
+          currentTool: null,
+          speechBubble: null,
+          lastActiveAt: 1774422913000,
+          toolCallCount: 0,
+          toolCallHistory: [],
+          runId: null,
+          isSubAgent: true,
+          isPlaceholder: false,
+          parentAgentId: "ceo-agent",
+          childAgentIds: [],
+          zone: "desk",
+          originalPosition: null,
+          movement: null,
+          confirmed: true,
+          arrivedAtHotDeskAt: null,
+          pendingRetire: false,
+          meta: {
+            department: "market",
+            boardFocusTaskId: null,
+            acceptedIdleCount: 0,
+          },
+        },
+        {
+          id: "daily-agent",
+          name: "daily-agent",
+          status: "idle",
+          position: { x: 640, y: 280 },
+          currentTool: null,
+          speechBubble: null,
+          lastActiveAt: 1774422913000,
+          toolCallCount: 0,
+          toolCallHistory: [],
+          runId: null,
+          isSubAgent: true,
+          isPlaceholder: false,
+          parentAgentId: "ceo-agent",
+          childAgentIds: [],
+          zone: "desk",
+          originalPosition: null,
+          movement: null,
+          confirmed: true,
+          arrivedAtHotDeskAt: null,
+          pendingRetire: false,
+          meta: {
+            department: "daily",
+            boardFocusTaskId: null,
+            acceptedIdleCount: 0,
+          },
+        },
+      ],
+      links: [
+        {
+          sourceId: "main",
+          targetId: "ceo-agent",
+          sessionKey: "org:main:ceo-agent",
+          strength: 0.35,
+          lastActivityAt: 1774422913000,
+        },
+        {
+          sourceId: "ceo-agent",
+          targetId: "engai-agent",
+          sessionKey: "org:ceo-agent:engai-agent",
+          strength: 0.35,
+          lastActivityAt: 1774422913000,
+        },
+        {
+          sourceId: "ceo-agent",
+          targetId: "content-agent",
+          sessionKey: "org:ceo-agent:content-agent",
+          strength: 0.35,
+          lastActivityAt: 1774422913000,
+        },
+        {
+          sourceId: "ceo-agent",
+          targetId: "market-agent",
+          sessionKey: "org:ceo-agent:market-agent",
+          strength: 0.35,
+          lastActivityAt: 1774422913000,
+        },
+        {
+          sourceId: "ceo-agent",
+          targetId: "daily-agent",
+          sessionKey: "org:ceo-agent:daily-agent",
+          strength: 0.35,
+          lastActivityAt: 1774422913000,
+        },
+        {
+          sourceId: "ceo-agent",
+          targetId: "engai-agent",
+          sessionKey: "tsk_mvp_bootstrap",
+          strength: 0.92,
+          lastActivityAt: 1774422913000,
+        },
+      ],
+      eventHistory: [
+        {
+          timestamp: 1774422913000,
+          agentId: "ceo-agent",
+          agentName: "CEO-agent",
+          stream: "assistant",
+          summary: "1 accepted-but-idle task(s) need owner motion",
+        },
+        {
+          timestamp: 1774422913000,
+          agentId: "main",
+          agentName: "main-agent",
+          stream: "assistant",
+          summary: "decision drift panel loaded with 1 deterministic example(s)",
+        },
+      ],
+      globalMetrics: {
+        activeAgents: 1,
+        totalAgents: 6,
+        totalTokens: 0,
+        tokenRate: 0,
+        collaborationHeat: 6,
+      },
+    },
+    panels: {
+      decisionDrift: {
+        panelId: "decision-drift",
+        title: "Decision drift",
+        severity: "warn",
+        summary: {
+          deterministicDecisionDriftCases: 1,
+          recentRealDecisionDriftCases: 4,
+          recentRealSuiteCases: 16,
+        },
+        items: [
+          {
+            kind: "deterministic-example",
+            caseId: "live_projection_pointer_override",
+            title: "Pointer cache tries to override live board focus",
+            driftTypes: ["decision_drift", "tool_order_drift", "projection_source_drift"],
+          },
+          {
+            kind: "recent-real-summary",
+            title: "Recent-real replay drift summary",
+            driftCounts: {
+              approval_branch_drift: 4,
+              decision_drift: 4,
+              tool_order_drift: 8,
+            },
+            examples: [
+              {
+                kind: "recent-real-example",
+                caseId: "live_content-agent_9de13d9b_decision",
+                title: "content-agent recent real transcript with edited assistant decision",
+                sourceSession: "content-agent",
+                detectedDriftTypes: ["decision_drift"],
+              },
+              {
+                kind: "recent-real-example",
+                caseId: "live_content-agent_9de13d9b_tool_order",
+                title: "content-agent recent real transcript with reordered tools",
+                sourceSession: "content-agent",
+                detectedDriftTypes: ["tool_order_drift"],
+              },
+              {
+                kind: "recent-real-example",
+                caseId: "live_content-agent_9de13d9b_approval",
+                title: "content-agent recent real transcript with inserted approval branch marker",
+                sourceSession: "content-agent",
+                detectedDriftTypes: ["approval_branch_drift", "tool_order_drift"],
+              },
+            ],
+          },
+        ],
+      },
+      toolFailure: {
+        panelId: "tool-failure",
+        title: "Tool failure",
+        severity: "info",
+        summary: {
+          count: 0,
+          state: "clear",
+        },
+        items: [],
+        emptyState: "No current tool failure surfaced by live board risk fronts or event summary.",
+      },
+      zombieTask: {
+        panelId: "zombie-task",
+        title: "Zombie task",
+        severity: "info",
+        summary: {
+          zombieRiskTasks: 0,
+          zombieEscalations: 0,
+        },
+        items: [],
+        emptyState: "No zombie-risk task is present in the current live board.",
+      },
+      handoffChain: {
+        panelId: "handoff-chain",
+        title: "Handoff chain",
+        severity: "warn",
+        summary: {
+          count: 1,
+          boardFocusCount: 1,
+          acceptedIdleCount: 1,
+        },
+        items: [
+          {
+            kind: "board-focus",
+            taskId: "tsk_mvp_bootstrap",
+            slug: "mvp-bootstrap",
+            title: "Spider Weaver MVP bootstrap",
+            chain: ["main", "ceo-agent", "engai-agent"],
+            chainLabels: ["main-agent", "CEO-agent", "engai-agent"],
+            owner: "engai-agent",
+            state: "accepted",
+            reason: "board-focus",
+            path: "/home/ubuntu/projects/spider-weaver/work/mvp-bootstrap",
+          },
+        ],
+        emptyState: null,
+      },
+    },
+    coverage: {
+      firstBatchPanels: 4,
+      sceneAgents: 6,
+    },
+  },
+} satisfies ProjectionBootstrapPacket;
+
diff --git a/src/store/__tests__/projection-bootstrap.test.ts b/src/store/__tests__/projection-bootstrap.test.ts
new file mode 100644
index 00000000..9103c8e0
--- /dev/null
+++ b/src/store/__tests__/projection-bootstrap.test.ts
@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { MOCK_PROJECTION_BOOTSTRAP } from "@/mock/projection-bootstrap";
+import { useOfficeStore } from "@/store/office-store";
+
+function resetStore() {
+  useOfficeStore.setState({
+    agents: new Map(),
+    links: [],
+    globalMetrics: {
+      activeAgents: 0,
+      totalAgents: 0,
+      totalTokens: 0,
+      tokenRate: 0,
+      collaborationHeat: 0,
+    },
+    connectionStatus: "disconnected",
+    connectionError: null,
+    selectedAgentId: null,
+    eventHistory: [],
+    sidebarCollapsed: false,
+    lastSessionsSnapshot: null,
+    projectionPanels: [],
+    theme: "dark",
+    operatorScopes: [],
+    tokenHistory: [],
+    agentCosts: {},
+    currentPage: "office",
+    chatDockHeight: 300,
+    maxSubAgents: 8,
+    agentToAgentConfig: { enabled: false, allow: [] },
+    runIdMap: new Map(),
+    sessionKeyMap: new Map(),
+  });
+}
+
+describe("projection bootstrap packet", () => {
+  beforeEach(resetStore);
+  afterEach(resetStore);
+
+  it("seeds office state from the framework bootstrap packet", () => {
+    useOfficeStore.getState().applyProjectionBootstrap(MOCK_PROJECTION_BOOTSTRAP);
+
+    const state = useOfficeStore.getState();
+    expect(state.agents.size).toBe(6);
+    expect(state.links).toHaveLength(6);
+    expect(state.eventHistory).toHaveLength(2);
+    expect(state.globalMetrics.totalAgents).toBe(6);
+    expect(state.globalMetrics.activeAgents).toBe(1);
+    expect(state.projectionPanels).toHaveLength(4);
+    expect(state.agents.get("ceo-agent")?.zone).toBe("meeting");
+    expect(state.agents.get("engai-agent")?.parentAgentId).toBe("ceo-agent");
+    expect(state.projectionPanels[0]?.panelId).toBe("decision-drift");
+    expect(state.projectionPanels[3]?.panelId).toBe("handoff-chain");
+  });
+});
+
diff --git a/src/store/office-store.ts b/src/store/office-store.ts
index 825bf039..31110d79 100644
--- a/src/store/office-store.ts
+++ b/src/store/office-store.ts
@@ -16,6 +16,7 @@ import type {
   EventHistoryItem,
   OfficeStore,
   PageId,
+  ProjectionBootstrapPacket,
   SessionSnapshot,
   SubAgentInfo,
   ThemeMode,
@@ -222,6 +223,7 @@ export const useOfficeStore = create<OfficeStore>()(
     eventHistory: [],
     sidebarCollapsed: true,
     lastSessionsSnapshot: null,
+    projectionPanels: [],
     theme: getInitialTheme(),
     operatorScopes: [] as string[],
     tokenHistory: [] as TokenSnapshot[],
@@ -663,6 +665,20 @@ export const useOfficeStore = create<OfficeStore>()(
       });
     },
 
+    applyProjectionBootstrap: (packet: ProjectionBootstrapPacket) => {
+      set((state) => {
+        const scene = packet.officeProjection.scene;
+        state.agents = new Map(scene.agents.map((agent) => [agent.id, agent as VisualAgent]));
+        state.links = [...scene.links];
+        state.globalMetrics = { ...scene.globalMetrics };
+        state.eventHistory = [...scene.eventHistory];
+        state.projectionPanels = Object.values(packet.officeProjection.panels);
+        state.runIdMap.clear();
+        state.sessionKeyMap.clear();
+        state.selectedAgentId = null;
+      });
+    },
+
     initAgents: (summaries: AgentSummary[]) => {
       set((state) => {
         state.agents.clear();
diff --git a/tests/setup.ts b/tests/setup.ts
index 2f0f16dc..69639a0e 100644
--- a/tests/setup.ts
+++ b/tests/setup.ts
@@ -1,2 +1,27 @@
 import "@testing-library/jest-dom/vitest";
 import "@/i18n/test-setup";
+
+if (typeof globalThis.localStorage === "undefined" || typeof globalThis.localStorage.getItem !== "function") {
+  const store = new Map<string, string>();
+  const localStorageMock = {
+    getItem: (key: string) => store.get(key) ?? null,
+    setItem: (key: string, value: string) => {
+      store.set(key, String(value));
+    },
+    removeItem: (key: string) => {
+      store.delete(key);
+    },
+    clear: () => {
+      store.clear();
+    },
+    key: (index: number) => Array.from(store.keys())[index] ?? null,
+    get length() {
+      return store.size;
+    },
+  } as Storage;
+
+  Object.defineProperty(globalThis, "localStorage", {
+    configurable: true,
+    value: localStorageMock,
+  });
+}