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/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/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>
   );
 }