address pr feedback

- Render OnboardingHero once, drive placement via CSS order toggle
- Document why derived onboarding steps don't emit step.completed
- Reconcile onboarding progress cache on PATCH failure via onError

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: camielvs

src/components/Learn/OnboardingHero.tsx

@@ -3,6 +3,7 @@ import { Button } from "@/components/ui/button";
 import { Icon } from "@/components/ui/icon";
 import { BlockStack, InlineStack } from "@/components/ui/layout";
 import { Heading, Paragraph } from "@/components/ui/typography";
+import { cn } from "@/lib/utils";
 import { useOnboarding } from "@/providers/OnboardingProvider/OnboardingProvider";
 
 function scrollNearestScrollableToTop(el: HTMLElement | null) {
@@ -21,12 +22,15 @@ function scrollNearestScrollableToTop(el: HTMLElement | null) {
   window.scrollTo({ top: 0, behavior: "smooth" });
 }
 
-export function OnboardingHero() {
+export function OnboardingHero({ className }: { className?: string }) {
   const { isComplete, dismissed, dismiss, reopen } = useOnboarding();
 
   if (dismissed) {
     return (
-      <InlineStack align="end" className="text-muted-foreground opacity-50">
+      <InlineStack
+        align="end"
+        className={cn("text-muted-foreground opacity-50", className)}
+      >
         <Button
           variant="ghost"
           size="sm"
@@ -46,7 +50,12 @@ export function OnboardingHero() {
   }
 
   return (
-    <div className="relative rounded-xl border border-border bg-linear-to-br from-primary/5 to-transparent p-6">
+    <div
+      className={cn(
+        "relative rounded-xl border border-border bg-linear-to-br from-primary/5 to-transparent p-6",
+        className,
+      )}
+    >
       <Button
         variant="ghost"
         size="icon"

src/components/shared/Submitters/Tangle/TangleSubmitter.tsx

@@ -12,6 +12,7 @@ import useCooldownTimer from "@/hooks/useCooldownTimer";
 import useToastNotification from "@/hooks/useToastNotification";
 import { cn } from "@/lib/utils";
 import { useBackend } from "@/providers/BackendProvider";
+import { ONBOARDING_MY_RUN_COUNT_KEY } from "@/providers/OnboardingProvider/onboardingQueryKeys";
 import { useTourMockBackend } from "@/providers/TourProvider/tourMockBackend";
 import { APP_ROUTES } from "@/routes/router";
 import { updateRunAnnotation } from "@/services/pipelineRunService";
@@ -91,6 +92,11 @@ function useSubmitPipeline() {
       await queryClient.invalidateQueries({
         queryKey: ["pipelineRuns"],
       });
+      // Refresh the onboarding checklist's run-count so a first run flips
+      // `execute_run` immediately rather than after the 5-minute stale window.
+      await queryClient.invalidateQueries({
+        queryKey: ONBOARDING_MY_RUN_COUNT_KEY,
+      });
     },
   });
 }

src/providers/OnboardingProvider/OnboardingProvider.test.tsx

@@ -6,6 +6,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { emitUserPipelineWritten } from "@/utils/userPipelineWriteEvents";
 
 import { OnboardingProvider, useOnboarding } from "./OnboardingProvider";
+import { ONBOARDING_MY_RUN_COUNT_KEY } from "./onboardingQueryKeys";
 
 const fetchWithErrorHandling = vi.hoisted(() =>
   vi.fn<(url: string, options?: RequestInit) => Promise<unknown>>(),
@@ -49,6 +50,21 @@ function render() {
   return renderHook(() => useOnboarding(), { wrapper });
 }
 
+function renderWithClient() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const clientWrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>
+      <OnboardingProvider>{children}</OnboardingProvider>
+    </QueryClientProvider>
+  );
+  return {
+    ...renderHook(() => useOnboarding(), { wrapper: clientWrapper }),
+    queryClient,
+  };
+}
+
 function completedSteps(result: { current: ReturnType<typeof useOnboarding> }) {
   return result.current.steps
     .filter((step) => step.completed)
@@ -110,6 +126,37 @@ describe("OnboardingProvider", () => {
     expect(patched()).toBe(false);
   });
 
+  it("refreshes execute_run when the run-count query is invalidated after a run is created", async () => {
+    const { result, queryClient } = renderWithClient();
+
+    await waitFor(() => expect(result.current.total).toBe(4));
+    expect(completedSteps(result)).not.toContain("execute_run");
+
+    // A run now exists, and the run-create mutation path invalidates the
+    // shared onboarding run-count key — execute_run should flip without
+    // waiting out the query's stale window.
+    runsPayload = { pipeline_runs: [{ id: "run-1" }] };
+    await act(async () => {
+      await queryClient.invalidateQueries({
+        queryKey: ONBOARDING_MY_RUN_COUNT_KEY,
+      });
+    });
+
+    await waitFor(() =>
+      expect(completedSteps(result)).toContain("execute_run"),
+    );
+    expect(patched()).toBe(false);
+  });
+
+  it("treats a malformed run-count payload as zero runs", async () => {
+    runsPayload = { pipeline_runs: "not-an-array" };
+
+    const { result } = render();
+
+    await waitFor(() => expect(result.current.total).toBe(4));
+    expect(completedSteps(result)).not.toContain("execute_run");
+  });
+
   it("persists create_pipeline when the user writes a pipeline", async () => {
     const { result } = render();
 

src/providers/OnboardingProvider/OnboardingProvider.tsx

@@ -1,7 +1,6 @@
 import { useQuery } from "@tanstack/react-query";
 import { type ReactNode, useEffect, useState } from "react";
 
-import type { ListPipelineJobsResponse } from "@/api/types.gen";
 import { useDocsVisitTracking } from "@/hooks/useDocsVisitTracking";
 import {
   createRequiredContext,
@@ -15,13 +14,15 @@ import {
   filtersToFilterQuery,
   parseFilterParam,
 } from "@/utils/pipelineRunFilterUtils";
+import { isRecord } from "@/utils/typeGuards";
 import { subscribeUserPipelineWritten } from "@/utils/userPipelineWriteEvents";
 
 import {
   type OnboardingSteps,
   useOnboardingProgress,
   usePersistOnboardingProgress,
 } from "./onboardingProgress";
+import { ONBOARDING_MY_RUN_COUNT_KEY } from "./onboardingQueryKeys";
 import {
   ONBOARDING_STEP_IDS,
   ONBOARDING_STEPS,
@@ -31,6 +32,11 @@ import {
 const PIPELINE_RUNS_QUERY_URL = "/api/pipeline_runs/";
 const STALE_MS = 1000 * 60 * 5;
 
+function countPipelineRuns(payload: unknown): number {
+  if (!isRecord(payload) || !Array.isArray(payload.pipeline_runs)) return 0;
+  return payload.pipeline_runs.length;
+}
+
 export interface OnboardingStep extends OnboardingStepMeta {
   completed: boolean;
 }
@@ -54,17 +60,15 @@ function useHasMyRun(): boolean {
   const filterQuery = filtersToFilterQuery(parseFilterParam("created_by:me"));
 
   const { data } = useQuery({
-    queryKey: ["onboarding", "myRunCount", backendUrl],
+    queryKey: [...ONBOARDING_MY_RUN_COUNT_KEY, backendUrl],
     enabled: available && Boolean(backendUrl),
     staleTime: STALE_MS,
     refetchOnWindowFocus: false,
     queryFn: async () => {
       const url = new URL(PIPELINE_RUNS_QUERY_URL, backendUrl);
       if (filterQuery) url.searchParams.set("filter_query", filterQuery);
-      const payload = (await fetchWithErrorHandling(
-        url.toString(),
-      )) as ListPipelineJobsResponse;
-      return payload.pipeline_runs?.length ?? 0;
+      const payload = await fetchWithErrorHandling(url.toString());
+      return countPipelineRuns(payload);
     },
   });
   return (data ?? 0) > 0;

src/providers/OnboardingProvider/onboardingProgress.ts

@@ -98,10 +98,12 @@ export function usePersistOnboardingProgress() {
         method: "PATCH",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ settings: { [ONBOARDING_KEY]: next } }),
-        // Often fired just before a navigation/reload; survive page unload.
         keepalive: true,
       });
     },
+    onError: () => {
+      queryClient.invalidateQueries({ queryKey: queryKey(backendUrl) });
+    },
   });
 
   return (next: OnboardingProgress) => {

src/providers/OnboardingProvider/onboardingQueryKeys.ts

@@ -0,0 +1,7 @@
+// Shared so the run-create mutation paths can invalidate the same query the
+// onboarding checklist reads to derive its `execute_run` step. Kept dependency
+// free so submitters can import it without pulling in the provider tree.
+export const ONBOARDING_MY_RUN_COUNT_KEY = [
+  "onboarding",
+  "myRunCount",
+] as const;

src/routes/Dashboard/Learn/LearnHomeView.tsx

@@ -26,7 +26,7 @@ export function LearnHomeView() {
         </BlockStack>
       </BlockStack>
 
-      {!dismissed && <OnboardingHero />}
+      <OnboardingHero className={dismissed ? "order-last" : undefined} />
 
       <div className="grid grid-cols-1 lg:grid-cols-2 gap-4">
         <TipOfTheDay />
@@ -43,8 +43,6 @@ export function LearnHomeView() {
           <HelpCard />
         </div>
       </div>
-
-      {dismissed && <OnboardingHero />}
     </BlockStack>
   );
 }

src/routes/v2/pages/Editor/components/AiChat/toolBridge.test.ts

@@ -8,6 +8,7 @@ import {
   Output,
   Task,
 } from "@/models/componentSpec";
+import { ONBOARDING_MY_RUN_COUNT_KEY } from "@/providers/OnboardingProvider/onboardingQueryKeys";
 import type { UndoGroupable } from "@/routes/v2/shared/nodes/types";
 
 vi.mock("@/services/componentService", () => ({
@@ -444,6 +445,9 @@ describe("createEditorToolBridge", () => {
       expect(urlArg).toBe(TEST_BACKEND_URL);
       expect(optionsArg.authorizationToken).toBe("auth-token");
       expect(invalidate).toHaveBeenCalledWith({ queryKey: ["pipelineRuns"] });
+      expect(invalidate).toHaveBeenCalledWith({
+        queryKey: ONBOARDING_MY_RUN_COUNT_KEY,
+      });
     });
 
     it("returns submission failure with the helper's error message", async () => {

src/routes/v2/shared/components/AiChat/toolBridge/runBridge.ts

@@ -26,6 +26,7 @@ import {
   truncateExecutionDetails,
 } from "@/agent/util/truncate";
 import { serializeComponentSpec } from "@/models/componentSpec/serialization/serialize";
+import { ONBOARDING_MY_RUN_COUNT_KEY } from "@/providers/OnboardingProvider/onboardingQueryKeys";
 import {
   fetchContainerExecutionState,
   fetchContainerLog,
@@ -85,6 +86,11 @@ export function createRunBridgeHandlers(deps: BridgeDeps): RunHandlers {
       }
       // Refresh both the editor list (per pipeline) and the home runs page.
       deps.queryClient?.invalidateQueries({ queryKey: ["pipelineRuns"] });
+      // Keep the onboarding checklist's run-count fresh so a first run flips
+      // `execute_run` immediately rather than after its stale window.
+      deps.queryClient?.invalidateQueries({
+        queryKey: ONBOARDING_MY_RUN_COUNT_KEY,
+      });
       return {
         success: true,
         runId: String(submission.run.id),