feat: refactor user configuration table

api/schemas/ai_model_configuration.py

@@ -34,10 +34,6 @@ class EffectiveAIModelConfiguration(BaseModel):
     test_phone_number: str | None = None
     timezone: str | None = None
     last_validated_at: datetime | None = None
-    # Post-signup onboarding gate: set once the user submits or skips the
-    # onboarding form, so it shows only once per user.
-    onboarding_completed_at: datetime | None = None
-    onboarding_skipped: bool = False
 
     @model_validator(mode="before")
     @classmethod

api/schemas/onboarding_state.py

@@ -0,0 +1,47 @@
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class OnboardingState(BaseModel):
+    """Per-user onboarding state, stored under UserConfigurationKey.ONBOARDING.
+
+    Server-authoritative replacement for the browser-localStorage onboarding
+    store, so the post-signup gate and one-time tooltips hold across devices.
+    """
+
+    # Post-signup onboarding form gate: set once on submit/skip.
+    completed_at: datetime | None = None
+    skipped: bool = False
+    # One-time UI affordances (tooltip keys, milestone action keys). Kept as
+    # free-form strings — the UI owns the vocabulary.
+    seen_tooltips: list[str] = Field(default_factory=list)
+    completed_actions: list[str] = Field(default_factory=list)
+
+
+class OnboardingStateUpdate(BaseModel):
+    """Partial update merged into the stored state.
+
+    Scalars overwrite when supplied; list entries are unioned into the stored
+    lists, so concurrent updates (e.g. two tabs marking different tooltips)
+    don't drop each other's items.
+    """
+
+    completed_at: datetime | None = None
+    skipped: bool | None = None
+    seen_tooltips: list[str] | None = None
+    completed_actions: list[str] | None = None
+
+    def apply_to(self, state: OnboardingState) -> OnboardingState:
+        merged = state.model_copy(deep=True)
+        if self.completed_at is not None:
+            merged.completed_at = self.completed_at
+        if self.skipped is not None:
+            merged.skipped = self.skipped
+        for tooltip in self.seen_tooltips or []:
+            if tooltip not in merged.seen_tooltips:
+                merged.seen_tooltips.append(tooltip)
+        for action in self.completed_actions or []:
+            if action not in merged.completed_actions:
+                merged.completed_actions.append(action)
+        return merged