diff --git a/apps/code/.storybook/preview.tsx b/apps/code/.storybook/preview.tsx
index 2e3787723..d53ba4046 100644
--- a/apps/code/.storybook/preview.tsx
+++ b/apps/code/.storybook/preview.tsx
@@ -30,7 +30,7 @@ const preview: Preview = {
           grayColor="slate"
           panelBackground="solid"
           radius="none"
-          scaling="105%"
+          scaling="100%"
         >
           <Story />
         </Theme>
diff --git a/apps/code/src/renderer/components/MainLayout.tsx b/apps/code/src/renderer/components/MainLayout.tsx
index f49e76d66..b45f5fa56 100644
--- a/apps/code/src/renderer/components/MainLayout.tsx
+++ b/apps/code/src/renderer/components/MainLayout.tsx
@@ -9,11 +9,15 @@ import { CommandCenterView } from "@features/command-center/components/CommandCe
 import { InboxView } from "@features/inbox/components/InboxView";
 import { FolderSettingsView } from "@features/settings/components/FolderSettingsView";
 import { SettingsDialog } from "@features/settings/components/SettingsDialog";
+import { useSettingsDialogStore } from "@features/settings/stores/settingsDialogStore";
 import { MainSidebar } from "@features/sidebar/components/MainSidebar";
 import { SkillsView } from "@features/skills/components/SkillsView";
 import { TaskDetail } from "@features/task-detail/components/TaskDetail";
 import { TaskInput } from "@features/task-detail/components/TaskInput";
 import { useTasks } from "@features/tasks/hooks/useTasks";
+import { TourOverlay } from "@features/tour/components/TourOverlay";
+import { useTourStore } from "@features/tour/stores/tourStore";
+import { createFirstTaskTour } from "@features/tour/tours/createFirstTaskTour";
 import { useConnectivity } from "@hooks/useConnectivity";
 import { useIntegrations } from "@hooks/useIntegrations";
 import { Box, Flex } from "@radix-ui/themes";
@@ -39,6 +43,11 @@ export function MainLayout() {
   const { data: tasks } = useTasks();
   const { showPrompt, isChecking, check, dismiss } = useConnectivity();
 
+  const startTour = useTourStore((s) => s.startTour);
+  const isFirstTaskTourDone = useTourStore((s) =>
+    s.completedTourIds.includes(createFirstTaskTour.id),
+  );
+
   useIntegrations();
   useTaskDeepLink();
 
@@ -54,6 +63,14 @@ export function MainLayout() {
     }
   }, [view, navigateToTaskInput]);
 
+  const settingsOpen = useSettingsDialogStore((s) => s.isOpen);
+
+  useEffect(() => {
+    if (isFirstTaskTourDone || settingsOpen) return;
+    const timer = setTimeout(() => startTour(createFirstTaskTour.id), 600);
+    return () => clearTimeout(timer);
+  }, [isFirstTaskTourDone, settingsOpen, startTour]);
+
   const handleToggleCommandMenu = useCallback(() => {
     toggleCommandMenu();
   }, [toggleCommandMenu]);
@@ -99,6 +116,7 @@ export function MainLayout() {
         onToggleShortcutsSheet={toggleShortcutsSheet}
       />
       <SettingsDialog />
+      <TourOverlay />
       <HedgehogMode />
     </Flex>
   );
diff --git a/apps/code/src/renderer/components/ThemeWrapper.tsx b/apps/code/src/renderer/components/ThemeWrapper.tsx
index 97dd6286d..bb3d6f72d 100644
--- a/apps/code/src/renderer/components/ThemeWrapper.tsx
+++ b/apps/code/src/renderer/components/ThemeWrapper.tsx
@@ -27,7 +27,7 @@ export function ThemeWrapper({ children }: { children: React.ReactNode }) {
       grayColor="slate"
       panelBackground="solid"
       radius="medium"
-      scaling="105%"
+      scaling="100%"
     >
       {children}
       <div ref={portalRef} id="portal-container" />
diff --git a/apps/code/src/renderer/features/settings/components/sections/AdvancedSettings.tsx b/apps/code/src/renderer/features/settings/components/sections/AdvancedSettings.tsx
index 40c1d4d37..4544d6902 100644
--- a/apps/code/src/renderer/features/settings/components/sections/AdvancedSettings.tsx
+++ b/apps/code/src/renderer/features/settings/components/sections/AdvancedSettings.tsx
@@ -2,6 +2,7 @@ import { useOnboardingStore } from "@features/onboarding/stores/onboardingStore"
 import { SettingRow } from "@features/settings/components/SettingRow";
 import { useSettingsDialogStore } from "@features/settings/stores/settingsDialogStore";
 import { useSettingsStore } from "@features/settings/stores/settingsStore";
+import { useTourStore } from "@features/tour/stores/tourStore";
 import { useFeatureFlag } from "@hooks/useFeatureFlag";
 import { Button, Flex, Switch } from "@radix-ui/themes";
 import { clearApplicationStorage } from "@utils/clearStorage";
@@ -31,6 +32,18 @@ export function AdvancedSettings() {
           Reset
         </Button>
       </SettingRow>
+      <SettingRow
+        label="Reset product tours"
+        description="Re-run product tours on next app restart"
+      >
+        <Button
+          variant="soft"
+          size="1"
+          onClick={() => useTourStore.getState().resetTours()}
+        >
+          Reset
+        </Button>
+      </SettingRow>
       <SettingRow
         label="Clear application storage"
         description="This will remove all locally stored application data"
diff --git a/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx b/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx
index 60bc232c4..6fdc1eeda 100644
--- a/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx
+++ b/apps/code/src/renderer/features/task-detail/components/TaskInput.tsx
@@ -443,7 +443,19 @@ export function TaskInput({
                 disabled={isCreatingTask}
               />
             )}
-            <ButtonGroup ref={buttonGroupRef}>
+            <ButtonGroup
+              ref={buttonGroupRef}
+              data-tour="folder-picker"
+              data-tour-ready={
+                (
+                  workspaceMode === "cloud"
+                    ? selectedRepository
+                    : selectedDirectory
+                )
+                  ? "true"
+                  : undefined
+              }
+            >
               {workspaceMode === "cloud" ? (
                 <GitHubRepoPicker
                   value={selectedRepository}
diff --git a/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts b/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts
index c2d2c9baa..3fae7a2cd 100644
--- a/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts
+++ b/apps/code/src/renderer/features/task-detail/hooks/useTaskCreation.ts
@@ -8,6 +8,8 @@ import {
 } from "@features/message-editor/utils/content";
 import { useSettingsStore } from "@features/settings/stores/settingsStore";
 import { useCreateTask } from "@features/tasks/hooks/useTasks";
+import { useTourStore } from "@features/tour/stores/tourStore";
+import { createFirstTaskTour } from "@features/tour/tours/createFirstTaskTour";
 import { useConnectivity } from "@hooks/useConnectivity";
 import type { WorkspaceMode } from "@main/services/workspace/schemas";
 import { get } from "@renderer/di/container";
@@ -170,6 +172,7 @@ export function useTaskCreation({
         } else {
           navigateToTask(output.task);
         }
+        useTourStore.getState().completeTour(createFirstTaskTour.id);
         editor.clear();
       });
 
diff --git a/apps/code/src/renderer/features/tour/components/TourOverlay.tsx b/apps/code/src/renderer/features/tour/components/TourOverlay.tsx
new file mode 100644
index 000000000..900391748
--- /dev/null
+++ b/apps/code/src/renderer/features/tour/components/TourOverlay.tsx
@@ -0,0 +1,149 @@
+import { useSettingsDialogStore } from "@features/settings/stores/settingsDialogStore";
+import { useCommandMenuStore } from "@stores/commandMenuStore";
+import { AnimatePresence, motion } from "framer-motion";
+import { useEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+import { useElementRect } from "../hooks/useElementRect";
+import { useTourStore } from "../stores/tourStore";
+import { TOUR_REGISTRY } from "../tours/tourRegistry";
+import { TourTooltip } from "./TourTooltip";
+
+const SPOTLIGHT_PADDING = 6;
+const SPOTLIGHT_RADIUS = 8;
+
+function SpotlightOverlay({ targetRect }: { targetRect: DOMRect | null }) {
+  return createPortal(
+    <AnimatePresence>
+      {targetRect && (
+        <motion.div
+          key="spotlight"
+          initial={{ opacity: 0 }}
+          animate={{
+            opacity: 1,
+            top: targetRect.top - SPOTLIGHT_PADDING,
+            left: targetRect.left - SPOTLIGHT_PADDING,
+            width: targetRect.width + SPOTLIGHT_PADDING * 2,
+            height: targetRect.height + SPOTLIGHT_PADDING * 2,
+          }}
+          exit={{ opacity: 0 }}
+          transition={{ type: "spring", stiffness: 200, damping: 25 }}
+          style={{
+            position: "fixed",
+            borderRadius: SPOTLIGHT_RADIUS,
+            boxShadow: "0 0 0 9999px rgba(0, 0, 0, 0.5)",
+            zIndex: 199,
+            pointerEvents: "none",
+          }}
+        />
+      )}
+    </AnimatePresence>,
+    document.body,
+  );
+}
+
+export function TourOverlay() {
+  const activeTourId = useTourStore((s) => s.activeTourId);
+  const activeStepIndex = useTourStore((s) => s.activeStepIndex);
+  const advance = useTourStore((s) => s.advance);
+  const dismiss = useTourStore((s) => s.dismiss);
+
+  const tour = activeTourId ? TOUR_REGISTRY[activeTourId] : null;
+  const step = tour?.steps[activeStepIndex] ?? null;
+
+  const selector = step ? `[data-tour="${step.target}"]` : null;
+  const targetRect = useElementRect(selector);
+
+  const advancedRef = useRef(false);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: reset on step change
+  useEffect(() => {
+    advancedRef.current = false;
+  }, [activeStepIndex]);
+
+  useEffect(() => {
+    if (!step || !activeTourId || step.advanceOn.type !== "click" || !selector)
+      return;
+
+    const el = document.querySelector(selector);
+    if (!el) return;
+
+    const tourId = activeTourId;
+    const stepId = step.id;
+    const handler = () => {
+      if (!advancedRef.current) {
+        advancedRef.current = true;
+        setTimeout(() => advance(tourId, stepId), 0);
+      }
+    };
+
+    el.addEventListener("click", handler, { capture: true });
+    return () => el.removeEventListener("click", handler, { capture: true });
+  }, [step, selector, advance, activeTourId]);
+
+  useEffect(() => {
+    if (!step || !activeTourId || step.advanceOn.type !== "action" || !selector)
+      return;
+
+    const tourId = activeTourId;
+    const stepId = step.id;
+    const SETTLE_MS = 2000;
+    let settleTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const tryAdvance = () => {
+      const el = document.querySelector(selector);
+      if (
+        el?.getAttribute("data-tour-ready") === "true" &&
+        !advancedRef.current
+      ) {
+        advancedRef.current = true;
+        advance(tourId, stepId);
+      }
+    };
+
+    const resetTimer = () => {
+      if (settleTimer) clearTimeout(settleTimer);
+      const el = document.querySelector(selector);
+      if (el?.getAttribute("data-tour-ready") === "true") {
+        settleTimer = setTimeout(tryAdvance, SETTLE_MS);
+      }
+    };
+
+    const observer = new MutationObserver(resetTimer);
+
+    const el = document.querySelector(selector);
+    if (el) {
+      observer.observe(el, {
+        subtree: true,
+        childList: true,
+        characterData: true,
+        attributes: true,
+      });
+      resetTimer();
+    }
+
+    return () => {
+      observer.disconnect();
+      if (settleTimer) clearTimeout(settleTimer);
+    };
+  }, [step, selector, advance, activeTourId]);
+
+  const settingsOpen = useSettingsDialogStore((s) => s.isOpen);
+  const commandMenuOpen = useCommandMenuStore((s) => s.isOpen);
+  const overlayBlocked = settingsOpen || commandMenuOpen;
+  const isActive = !!(tour && step && targetRect && !overlayBlocked);
+
+  return (
+    <>
+      <SpotlightOverlay targetRect={isActive ? targetRect : null} />
+      {isActive && (
+        <TourTooltip
+          step={step}
+          stepNumber={activeStepIndex + 1}
+          totalSteps={tour.steps.length}
+          onDismiss={dismiss}
+          targetRect={targetRect}
+        />
+      )}
+    </>
+  );
+}
diff --git a/apps/code/src/renderer/features/tour/components/TourTooltip.tsx b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx
new file mode 100644
index 000000000..562ebb3b3
--- /dev/null
+++ b/apps/code/src/renderer/features/tour/components/TourTooltip.tsx
@@ -0,0 +1,356 @@
+import { Button, Flex, Text, Theme } from "@radix-ui/themes";
+import { useThemeStore } from "@stores/themeStore";
+import { AnimatePresence, motion, useAnimationControls } from "framer-motion";
+import { useEffect } from "react";
+import { createPortal } from "react-dom";
+import type { TooltipPlacement, TourStep } from "../types";
+import { calculateTooltipPlacement } from "../utils/calculateTooltipPlacement";
+
+interface TourTooltipProps {
+  step: TourStep;
+  stepNumber: number;
+  totalSteps: number;
+  onDismiss: () => void;
+  targetRect: DOMRect;
+}
+
+const HOG_SIZE = 64;
+const HOG_GAP = 8;
+const BUBBLE_MAX_WIDTH = 280;
+const TOOLTIP_WIDTH_ESTIMATE = BUBBLE_MAX_WIDTH + HOG_GAP + HOG_SIZE;
+const TOOLTIP_HEIGHT_ESTIMATE = 100;
+
+const CARET_SIZE = 12;
+const CARET_INNER = 11;
+
+const talkingAnimation = {
+  rotate: [0, -3, 3, -2, 2, 0],
+  y: [0, -2, 0, -1, 0],
+  transition: {
+    duration: 0.4,
+    repeat: Infinity,
+    repeatDelay: 0.1,
+  },
+};
+
+const hogEntranceVariants = {
+  initial: { opacity: 0, scale: 0.5 },
+  animate: {
+    opacity: 1,
+    scale: 1,
+    transition: {
+      type: "spring" as const,
+      stiffness: 400,
+      damping: 18,
+      delay: 0.15,
+    },
+  },
+  exit: {
+    opacity: 0,
+    scale: 0.5,
+    transition: { duration: 0.1 },
+  },
+};
+
+const CARET_SIDE_MAP: Record<
+  TooltipPlacement,
+  "left" | "right" | "top" | "bottom"
+> = {
+  right: "left",
+  left: "right",
+  bottom: "top",
+  top: "bottom",
+};
+
+const TRANSFORM_ORIGIN_MAP: Record<TooltipPlacement, string> = {
+  right: "left center",
+  left: "right center",
+  bottom: "top center",
+  top: "bottom center",
+};
+
+function getBubbleVariants(placement: TooltipPlacement) {
+  const dx = placement === "right" ? 12 : placement === "left" ? -12 : 0;
+  const dy = placement === "bottom" ? -12 : placement === "top" ? 12 : 0;
+
+  return {
+    initial: { opacity: 0, scale: 0.92, x: dx, y: dy },
+    animate: {
+      opacity: 1,
+      scale: 1,
+      x: 0,
+      y: 0,
+      transition: { type: "spring" as const, stiffness: 300, damping: 24 },
+    },
+    exit: {
+      opacity: 0,
+      scale: 0.95,
+      x: dx * 0.5,
+      y: dy * 0.5,
+      transition: { duration: 0.15 },
+    },
+  };
+}
+
+function Caret({
+  side,
+  offset = 0,
+}: {
+  side: "left" | "right" | "top" | "bottom";
+  offset?: number;
+}) {
+  const borderColor = "var(--gray-a5)";
+  const fillColor = "var(--color-panel-solid)";
+
+  const base: React.CSSProperties = {
+    position: "absolute",
+    width: 0,
+    height: 0,
+  };
+
+  switch (side) {
+    case "right":
+      return (
+        <>
+          <div
+            style={{
+              ...base,
+              top: `calc(50% + ${offset}px)`,
+              right: -CARET_SIZE,
+              marginTop: -CARET_SIZE,
+              borderTop: `${CARET_SIZE}px solid transparent`,
+              borderBottom: `${CARET_SIZE}px solid transparent`,
+              borderLeft: `${CARET_SIZE}px solid ${borderColor}`,
+            }}
+          />
+          <div
+            style={{
+              ...base,
+              top: `calc(50% + ${offset}px)`,
+              right: -CARET_INNER,
+              marginTop: -CARET_INNER,
+              borderTop: `${CARET_INNER}px solid transparent`,
+              borderBottom: `${CARET_INNER}px solid transparent`,
+              borderLeft: `${CARET_INNER}px solid ${fillColor}`,
+            }}
+          />
+        </>
+      );
+    case "left":
+      return (
+        <>
+          <div
+            style={{
+              ...base,
+              top: `calc(50% + ${offset}px)`,
+              left: -CARET_SIZE,
+              marginTop: -CARET_SIZE,
+              borderTop: `${CARET_SIZE}px solid transparent`,
+              borderBottom: `${CARET_SIZE}px solid transparent`,
+              borderRight: `${CARET_SIZE}px solid ${borderColor}`,
+            }}
+          />
+          <div
+            style={{
+              ...base,
+              top: `calc(50% + ${offset}px)`,
+              left: -CARET_INNER,
+              marginTop: -CARET_INNER,
+              borderTop: `${CARET_INNER}px solid transparent`,
+              borderBottom: `${CARET_INNER}px solid transparent`,
+              borderRight: `${CARET_INNER}px solid ${fillColor}`,
+            }}
+          />
+        </>
+      );
+    case "top":
+      return (
+        <>
+          <div
+            style={{
+              ...base,
+              left: `calc(50% + ${offset}px)`,
+              top: -CARET_SIZE,
+              marginLeft: -CARET_SIZE,
+              borderLeft: `${CARET_SIZE}px solid transparent`,
+              borderRight: `${CARET_SIZE}px solid transparent`,
+              borderBottom: `${CARET_SIZE}px solid ${borderColor}`,
+            }}
+          />
+          <div
+            style={{
+              ...base,
+              left: `calc(50% + ${offset}px)`,
+              top: -CARET_INNER,
+              marginLeft: -CARET_INNER,
+              borderLeft: `${CARET_INNER}px solid transparent`,
+              borderRight: `${CARET_INNER}px solid transparent`,
+              borderBottom: `${CARET_INNER}px solid ${fillColor}`,
+            }}
+          />
+        </>
+      );
+    case "bottom":
+      return (
+        <>
+          <div
+            style={{
+              ...base,
+              left: `calc(50% + ${offset}px)`,
+              bottom: -CARET_SIZE,
+              marginLeft: -CARET_SIZE,
+              borderLeft: `${CARET_SIZE}px solid transparent`,
+              borderRight: `${CARET_SIZE}px solid transparent`,
+              borderTop: `${CARET_SIZE}px solid ${borderColor}`,
+            }}
+          />
+          <div
+            style={{
+              ...base,
+              left: `calc(50% + ${offset}px)`,
+              bottom: -CARET_INNER,
+              marginLeft: -CARET_INNER,
+              borderLeft: `${CARET_INNER}px solid transparent`,
+              borderRight: `${CARET_INNER}px solid transparent`,
+              borderTop: `${CARET_INNER}px solid ${fillColor}`,
+            }}
+          />
+        </>
+      );
+  }
+}
+
+export function TourTooltip({
+  step,
+  stepNumber,
+  totalSteps,
+  onDismiss,
+  targetRect,
+}: TourTooltipProps) {
+  const isDarkMode = useThemeStore((s) => s.isDarkMode);
+  const controls = useAnimationControls();
+
+  const { placement, x, y, arrowOffset } = calculateTooltipPlacement(
+    targetRect,
+    TOOLTIP_WIDTH_ESTIMATE,
+    TOOLTIP_HEIGHT_ESTIMATE,
+    step.preferredPlacement,
+  );
+
+  const caretSide = CARET_SIDE_MAP[placement];
+  const hogOnRight = true;
+  const bubbleVariants = getBubbleVariants(placement);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: restart animation on step change
+  useEffect(() => {
+    controls.stop();
+    const timer = setTimeout(() => {
+      controls.start(talkingAnimation);
+    }, 500);
+    return () => clearTimeout(timer);
+  }, [controls, step.id]);
+
+  const hogElement = (
+    <motion.div
+      variants={hogEntranceVariants}
+      initial="initial"
+      animate="animate"
+      exit="exit"
+      style={{
+        flexShrink: 0,
+        ...(hogOnRight ? { marginLeft: HOG_GAP } : { marginRight: HOG_GAP }),
+      }}
+    >
+      <motion.img
+        src={step.hogSrc}
+        alt=""
+        animate={controls}
+        style={{
+          width: HOG_SIZE,
+          height: HOG_SIZE,
+          objectFit: "contain",
+        }}
+      />
+    </motion.div>
+  );
+
+  return createPortal(
+    <Theme
+      appearance={isDarkMode ? "dark" : "light"}
+      accentColor={isDarkMode ? "yellow" : "orange"}
+      grayColor="slate"
+      panelBackground="solid"
+      radius="medium"
+      style={{
+        position: "fixed",
+        top: 0,
+        left: 0,
+        zIndex: 201,
+        pointerEvents: "none",
+      }}
+    >
+      <AnimatePresence mode="wait">
+        <div
+          key={step.id}
+          style={{
+            position: "fixed",
+            top: y,
+            left: x,
+            zIndex: 201,
+            pointerEvents: "auto",
+            display: "flex",
+            alignItems: "center",
+            gap: 0,
+          }}
+        >
+          {!hogOnRight && hogElement}
+
+          <motion.div
+            variants={bubbleVariants}
+            initial="initial"
+            animate="animate"
+            exit="exit"
+            style={{
+              position: "relative",
+              backgroundColor: "var(--color-panel-solid)",
+              border: "1px solid var(--gray-a5)",
+              borderRadius: "var(--radius-3)",
+              padding: "14px 18px",
+              maxWidth: BUBBLE_MAX_WIDTH,
+              boxShadow:
+                "0 8px 24px rgba(0, 0, 0, 0.15), 0 2px 6px rgba(0, 0, 0, 0.08)",
+              transformOrigin: TRANSFORM_ORIGIN_MAP[placement],
+            }}
+          >
+            <Caret side={caretSide} offset={arrowOffset} />
+            <Flex direction="column" gap="2">
+              <Text
+                size="2"
+                style={{ color: "var(--gray-12)", lineHeight: 1.5 }}
+              >
+                {step.message}
+              </Text>
+              <Flex justify="between" align="center" gap="3">
+                <Text size="1" style={{ color: "var(--gray-9)" }}>
+                  {stepNumber}/{totalSteps}
+                </Text>
+                <Button
+                  size="1"
+                  variant="ghost"
+                  color="gray"
+                  onClick={onDismiss}
+                  style={{ opacity: 0.5 }}
+                >
+                  Skip tour
+                </Button>
+              </Flex>
+            </Flex>
+          </motion.div>
+
+          {hogOnRight && hogElement}
+        </div>
+      </AnimatePresence>
+    </Theme>,
+    document.body,
+  );
+}
diff --git a/apps/code/src/renderer/features/tour/hooks/useElementRect.ts b/apps/code/src/renderer/features/tour/hooks/useElementRect.ts
new file mode 100644
index 000000000..3b0e01a7b
--- /dev/null
+++ b/apps/code/src/renderer/features/tour/hooks/useElementRect.ts
@@ -0,0 +1,43 @@
+import { useEffect, useState } from "react";
+
+function rectsEqual(a: DOMRect | null, b: DOMRect | null): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return (
+    Math.abs(a.top - b.top) < 1 &&
+    Math.abs(a.left - b.left) < 1 &&
+    Math.abs(a.width - b.width) < 1 &&
+    Math.abs(a.height - b.height) < 1
+  );
+}
+
+export function useElementRect(selector: string | null): DOMRect | null {
+  const [rect, setRect] = useState<DOMRect | null>(null);
+
+  useEffect(() => {
+    if (!selector) {
+      setRect(null);
+      return;
+    }
+
+    let frameId: number;
+    let prevRect: DOMRect | null = null;
+
+    const poll = () => {
+      const el = document.querySelector(selector);
+      const nextRect = el?.getBoundingClientRect() ?? null;
+
+      if (!rectsEqual(nextRect, prevRect)) {
+        prevRect = nextRect;
+        setRect(nextRect ? DOMRect.fromRect(nextRect) : null);
+      }
+
+      frameId = requestAnimationFrame(poll);
+    };
+
+    frameId = requestAnimationFrame(poll);
+    return () => cancelAnimationFrame(frameId);
+  }, [selector]);
+
+  return rect;
+}
diff --git a/apps/code/src/renderer/features/tour/hooks/useTour.ts b/apps/code/src/renderer/features/tour/hooks/useTour.ts
new file mode 100644
index 000000000..3f9a7e435
--- /dev/null
+++ b/apps/code/src/renderer/features/tour/hooks/useTour.ts
@@ -0,0 +1,13 @@
+import { useTourStore } from "../stores/tourStore";
+
+export function useTour() {
+  const startTour = useTourStore((s) => s.startTour);
+  const dismiss = useTourStore((s) => s.dismiss);
+  const completedTourIds = useTourStore((s) => s.completedTourIds);
+
+  return {
+    startTour,
+    dismiss,
+    isCompleted: (tourId: string) => completedTourIds.includes(tourId),
+  };
+}
diff --git a/apps/code/src/renderer/features/tour/stores/tourStore.ts b/apps/code/src/renderer/features/tour/stores/tourStore.ts
new file mode 100644
index 000000000..ca96e9aa3
--- /dev/null
+++ b/apps/code/src/renderer/features/tour/stores/tourStore.ts
@@ -0,0 +1,90 @@
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import { TOUR_REGISTRY } from "../tours/tourRegistry";
+
+interface TourStoreState {
+  completedTourIds: string[];
+  activeTourId: string | null;
+  activeStepIndex: number;
+}
+
+interface TourStoreActions {
+  startTour: (tourId: string) => void;
+  advance: (tourId: string, stepId: string) => void;
+  completeTour: (tourId: string) => void;
+  dismiss: () => void;
+  resetTours: () => void;
+}
+
+type TourStore = TourStoreState & TourStoreActions;
+
+export const useTourStore = create<TourStore>()(
+  persist(
+    (set, get) => ({
+      completedTourIds: [],
+      activeTourId: null,
+      activeStepIndex: 0,
+
+      startTour: (tourId) => {
+        const { completedTourIds, activeTourId } = get();
+        if (completedTourIds.includes(tourId) || activeTourId === tourId)
+          return;
+        set({ activeTourId: tourId, activeStepIndex: 0 });
+      },
+
+      advance: (tourId, stepId) => {
+        const { activeTourId, activeStepIndex } = get();
+        if (activeTourId !== tourId) return;
+
+        const tour = TOUR_REGISTRY[activeTourId];
+        if (!tour) return;
+
+        const currentStep = tour.steps[activeStepIndex];
+        if (!currentStep || currentStep.id !== stepId) return;
+
+        if (activeStepIndex >= tour.steps.length - 1) {
+          set((state) => {
+            if (!state.activeTourId) return state;
+            return {
+              completedTourIds: [...state.completedTourIds, state.activeTourId],
+              activeTourId: null,
+              activeStepIndex: 0,
+            };
+          });
+        } else {
+          set({ activeStepIndex: activeStepIndex + 1 });
+        }
+      },
+
+      completeTour: (tourId) => {
+        const { completedTourIds } = get();
+        if (completedTourIds.includes(tourId)) return;
+        set({
+          completedTourIds: [...completedTourIds, tourId],
+          activeTourId: null,
+          activeStepIndex: 0,
+        });
+      },
+
+      dismiss: () => {
+        const { activeTourId } = get();
+        if (!activeTourId) return;
+        set((state) => ({
+          completedTourIds: [...state.completedTourIds, activeTourId],
+          activeTourId: null,
+          activeStepIndex: 0,
+        }));
+      },
+
+      resetTours: () => {
+        set({ completedTourIds: [], activeTourId: null, activeStepIndex: 0 });
+      },
+    }),
+    {
+      name: "tour-store",
+      partialize: (state) => ({
+        completedTourIds: state.completedTourIds,
+      }),
+    },
+  ),
+);
diff --git a/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts
new file mode 100644
index 000000000..9305ee45b
--- /dev/null
+++ b/apps/code/src/renderer/features/tour/tours/createFirstTaskTour.ts
@@ -0,0 +1,32 @@
+import builderHog from "@renderer/assets/images/hedgehogs/builder-hog-03.png";
+import explorerHog from "@renderer/assets/images/hedgehogs/explorer-hog.png";
+import happyHog from "@renderer/assets/images/hedgehogs/happy-hog.png";
+import type { TourDefinition } from "../types";
+
+export const createFirstTaskTour: TourDefinition = {
+  id: "create-first-task",
+  steps: [
+    {
+      id: "folder-picker",
+      target: "folder-picker",
+      hogSrc: explorerHog,
+      message: "Pick a repo to work with. This tells me where your code lives!",
+      advanceOn: { type: "action" },
+    },
+    {
+      id: "task-editor",
+      target: "task-input-editor",
+      hogSrc: builderHog,
+      message:
+        "Describe what you want to build or fix. Be as specific as you like!",
+      advanceOn: { type: "action" },
+    },
+    {
+      id: "submit-button",
+      target: "submit-button",
+      hogSrc: happyHog,
+      message: "Hit send or press Enter to launch your first agent!",
+      advanceOn: { type: "click" },
+    },
+  ],
+};
diff --git a/apps/code/src/renderer/features/tour/tours/tourRegistry.ts b/apps/code/src/renderer/features/tour/tours/tourRegistry.ts
new file mode 100644
index 000000000..c5c4b0f94
--- /dev/null
+++ b/apps/code/src/renderer/features/tour/tours/tourRegistry.ts
@@ -0,0 +1,6 @@
+import type { TourDefinition } from "../types";
+import { createFirstTaskTour } from "./createFirstTaskTour";
+
+export const TOUR_REGISTRY: Record<string, TourDefinition> = {
+  [createFirstTaskTour.id]: createFirstTaskTour,
+};
diff --git a/apps/code/src/renderer/features/tour/types.ts b/apps/code/src/renderer/features/tour/types.ts
new file mode 100644
index 000000000..939653ba7
--- /dev/null
+++ b/apps/code/src/renderer/features/tour/types.ts
@@ -0,0 +1,17 @@
+export type TourStepAdvance = { type: "action" } | { type: "click" };
+
+export type TooltipPlacement = "right" | "left" | "top" | "bottom";
+
+export interface TourStep {
+  id: string;
+  target: string;
+  hogSrc: string;
+  message: string;
+  advanceOn: TourStepAdvance;
+  preferredPlacement?: TooltipPlacement;
+}
+
+export interface TourDefinition {
+  id: string;
+  steps: TourStep[];
+}
diff --git a/apps/code/src/renderer/features/tour/utils/calculateTooltipPlacement.ts b/apps/code/src/renderer/features/tour/utils/calculateTooltipPlacement.ts
new file mode 100644
index 000000000..b7417f9b7
--- /dev/null
+++ b/apps/code/src/renderer/features/tour/utils/calculateTooltipPlacement.ts
@@ -0,0 +1,115 @@
+import type { TooltipPlacement } from "../types";
+
+const TOOLTIP_MARGIN = 12;
+const VIEWPORT_PADDING = 8;
+
+const DEFAULT_ORDER: TooltipPlacement[] = ["right", "left", "top", "bottom"];
+
+export interface PlacedTooltip {
+  placement: TooltipPlacement;
+  x: number;
+  y: number;
+  arrowOffset: number;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+export function calculateTooltipPlacement(
+  targetRect: DOMRect,
+  tooltipWidth: number,
+  tooltipHeight: number,
+  preferred?: TooltipPlacement,
+): PlacedTooltip {
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+
+  const spaceRight = vw - targetRect.right;
+  const spaceLeft = targetRect.left;
+  const spaceAbove = targetRect.top;
+
+  const targetCenterX = targetRect.left + targetRect.width / 2;
+  const targetCenterY = targetRect.top + targetRect.height / 2;
+
+  const order = preferred
+    ? [preferred, ...DEFAULT_ORDER.filter((p) => p !== preferred)]
+    : DEFAULT_ORDER;
+
+  for (const placement of order) {
+    switch (placement) {
+      case "right": {
+        if (spaceRight < tooltipWidth + TOOLTIP_MARGIN) break;
+        const idealY = targetCenterY - tooltipHeight / 2;
+        const y = clamp(
+          idealY,
+          VIEWPORT_PADDING,
+          vh - VIEWPORT_PADDING - tooltipHeight,
+        );
+        return {
+          placement,
+          x: targetRect.right + TOOLTIP_MARGIN,
+          y,
+          arrowOffset: idealY - y,
+        };
+      }
+      case "left": {
+        if (spaceLeft < tooltipWidth + TOOLTIP_MARGIN) break;
+        const idealY = targetCenterY - tooltipHeight / 2;
+        const y = clamp(
+          idealY,
+          VIEWPORT_PADDING,
+          vh - VIEWPORT_PADDING - tooltipHeight,
+        );
+        return {
+          placement,
+          x: targetRect.left - TOOLTIP_MARGIN - tooltipWidth,
+          y,
+          arrowOffset: idealY - y,
+        };
+      }
+      case "top": {
+        if (spaceAbove < tooltipHeight + TOOLTIP_MARGIN) break;
+        const idealX = targetCenterX - tooltipWidth / 2;
+        const x = clamp(
+          idealX,
+          VIEWPORT_PADDING,
+          vw - VIEWPORT_PADDING - tooltipWidth,
+        );
+        return {
+          placement,
+          x,
+          y: targetRect.top - TOOLTIP_MARGIN - tooltipHeight,
+          arrowOffset: idealX - x,
+        };
+      }
+      case "bottom": {
+        const idealX = targetCenterX - tooltipWidth / 2;
+        const x = clamp(
+          idealX,
+          VIEWPORT_PADDING,
+          vw - VIEWPORT_PADDING - tooltipWidth,
+        );
+        return {
+          placement,
+          x,
+          y: targetRect.bottom + TOOLTIP_MARGIN,
+          arrowOffset: idealX - x,
+        };
+      }
+    }
+  }
+
+  const idealX = targetCenterX - tooltipWidth / 2;
+  const x = clamp(
+    idealX,
+    VIEWPORT_PADDING,
+    vw - VIEWPORT_PADDING - tooltipWidth,
+  );
+  return {
+    placement: "bottom",
+    x,
+    y: targetRect.bottom + TOOLTIP_MARGIN,
+    arrowOffset: idealX - x,
+  };
+}