From 0f881097bca00e70618fedd842bff37a0c8e89ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?=
 <zhangyanghaha0407@outlook.com>
Date: Thu, 16 Apr 2026 23:28:04 -0400
Subject: [PATCH] docs(snapshot): tag profile-level vs company-scoped fields

Adds an inline comment partition and typed PROFILE_LEVEL_KEYS /
COMPANY_SCOPED_KEYS constants on ProfileSnapshot so callers can
reason about which fields survive a company switch. Shape is
unchanged; renderer consumption is unaffected.
---
 src/shared/types/snapshot.ts | 40 ++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/src/shared/types/snapshot.ts b/src/shared/types/snapshot.ts
index 4578d204..f401b979 100644
--- a/src/shared/types/snapshot.ts
+++ b/src/shared/types/snapshot.ts
@@ -25,6 +25,7 @@ import type {
 } from "./records-extended";
 
 export interface ProfileSnapshot {
+  // ─── Profile-level (shared across all companies) ─────────────────────────
   currentCompanyId: string | null;
   profilePath: string;
   updatesEnabled: boolean;
@@ -35,6 +36,7 @@ export interface ProfileSnapshot {
   };
   companies: CompanyRecord[];
   connectors: ConnectorRecord[];
+  // ─── Company-scoped collections (current company only) ───────────────────
   workspaces: WorkspaceRecord[];
   agents: AgentRecord[];
   goals: GoalRecord[];
@@ -56,3 +58,41 @@ export interface ProfileSnapshot {
   workflows: WorkflowPipelineRecord[];
 }
 
+/** Fields that are shared across companies and loaded regardless of currentCompanyId. */
+export const PROFILE_LEVEL_KEYS = [
+  "currentCompanyId",
+  "profilePath",
+  "updatesEnabled",
+  "theme",
+  "locale",
+  "backend",
+  "companies",
+  "connectors",
+] as const satisfies ReadonlyArray<keyof ProfileSnapshot>;
+
+/** Fields that are filtered to the current company; switching companies reloads these. */
+export const COMPANY_SCOPED_KEYS = [
+  "workspaces",
+  "agents",
+  "goals",
+  "projects",
+  "tasks",
+  "approvals",
+  "runs",
+  "costs",
+  "activity",
+  "secrets",
+  "comments",
+  "socialAccounts",
+  "meetings",
+  "documents",
+  "knowledgeBase",
+  "sprints",
+  "automationRules",
+  "agentMessages",
+  "workflows",
+] as const satisfies ReadonlyArray<keyof ProfileSnapshot>;
+
+export type ProfileLevelKey = typeof PROFILE_LEVEL_KEYS[number];
+export type CompanyScopedKey = typeof COMPANY_SCOPED_KEYS[number];
+