diff --git a/src/lib/query-keys/index.ts b/src/lib/query-keys/index.ts
index dbec8a3e2..3fc184256 100644
--- a/src/lib/query-keys/index.ts
+++ b/src/lib/query-keys/index.ts
@@ -36,6 +36,7 @@ import { medicationKeys } from "./medications";
 import { mentalHealthKeys } from "./mental-health";
 import { moodKeys } from "./mood";
 import { nutrientKeys } from "./nutrients";
+import { onboardingKeys } from "./onboarding";
 import { recordSettingsKeys } from "./record-settings";
 import { profileKeys } from "./profile";
 import { settingsKeys } from "./settings";
@@ -68,6 +69,7 @@ export const queryKeys = {
   ...encounterKeys,
   ...customMetrics,
   ...nutrientKeys,
+  ...onboardingKeys,
   ...recordSettingsKeys,
   ...profileKeys,
   ...sharingKeys,
diff --git a/src/lib/query-keys/onboarding.ts b/src/lib/query-keys/onboarding.ts
new file mode 100644
index 000000000..6538823f8
--- /dev/null
+++ b/src/lib/query-keys/onboarding.ts
@@ -0,0 +1,27 @@
+/**
+ * Query keys — the needs-based setup flow (v1.39 C2).
+ * Part of the centralized factory; aggregated in `./index.ts`.
+ *
+ * The flow has no read of its own: its state rides `GET /api/auth/me` as
+ * `onboarding`, so every screen reads `queryKeys.authMe()` and every write
+ * below invalidates it. What lives here are the mutation keys, one per
+ * endpoint, so a screen that persists an answer and a settings card that
+ * restarts the flow cannot collide on an anonymous mutation.
+ */
+export const onboardingKeys = {
+  /** `PATCH /api/onboarding/answers` — one step, answered or skipped. */
+  onboardingAnswerMutation: () => ["onboarding", "answer"] as const,
+  /** `POST /api/onboarding/complete` — the confirm screen, and "skip for now". */
+  onboardingCompleteMutation: () => ["onboarding", "complete"] as const,
+  /** `POST /api/onboarding/restart` — "Set up again", from Settings. */
+  onboardingRestartMutation: () => ["onboarding", "restart"] as const,
+  /** `POST /api/onboarding/disclaimer` — the one-time acknowledgment. */
+  onboardingDisclaimerMutation: () => ["onboarding", "disclaimer"] as const,
+  /**
+   * The latest reading of one type, read back after the first-result step
+   * logged it so the screen can show the value on its tile. Rides under the
+   * `["measurements"]` prefix so `measurementDependentKeys` evicts it.
+   */
+  onboardingLatestReading: (type: string) =>
+    ["measurements", "onboarding-latest", type] as const,
+};