diff --git a/packages/cli/src/server/desktopRoutes.test.ts b/packages/cli/src/server/desktopRoutes.test.ts
index 986ca3cd5a..c583de0aac 100644
--- a/packages/cli/src/server/desktopRoutes.test.ts
+++ b/packages/cli/src/server/desktopRoutes.test.ts
@@ -19,10 +19,14 @@ function server(
   place: { platform?: NodeJS.Platform; installed?: () => boolean } = {},
 ) {
   const app = new Hono();
-  const open = vi.fn((_dir: string): DesktopOpenResult => OPENED);
+  const open = vi.fn((_dir: string, _cta?: string): DesktopOpenResult => OPENED);
   mountDesktopRoutes(app, "/films/a", { ready, open, ...place });
-  const post = (headers: Record<string, string>) =>
-    app.request("/api/open-in-desktop", { method: "POST", headers });
+  const post = (headers: Record<string, string>, body?: unknown) =>
+    app.request("/api/open-in-desktop", {
+      method: "POST",
+      headers: body === undefined ? headers : { ...headers, "content-type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
   return { app, open, post };
 }
 
@@ -32,7 +36,13 @@ describe("open-in-desktop routes", () => {
       await server(false, { installed: () => false }).app.request("/api/open-in-desktop")
     ).json();
     const downloadUrl = desktopDownloadUrl();
-    expect(body).toEqual({ available: downloadUrl !== null, handoff: false, downloadUrl });
+    expect(body).toEqual({
+      available: downloadUrl !== null,
+      handoff: false,
+      downloadUrl,
+      os: process.platform,
+      installed: false,
+    });
   });
 
   it("shows the button where the app is installed even without a download (Windows)", async () => {
@@ -42,10 +52,33 @@ describe("open-in-desktop routes", () => {
           "/api/open-in-desktop",
         )
       ).json();
-    expect(await get(true)).toEqual({ available: true, handoff: true, downloadUrl: null });
+    expect(await get(true)).toEqual({
+      available: true,
+      handoff: true,
+      downloadUrl: null,
+      os: "win32",
+      installed: true,
+    });
     expect(await get(false)).toMatchObject({ available: false });
   });
 
+  it("offers the hand-off only where the app is installed, so a press without it goes to the download", async () => {
+    const get = async (installed: boolean) =>
+      (
+        await server(true, { platform: "darwin", installed: () => installed }).app.request(
+          "/api/open-in-desktop",
+        )
+      ).json();
+    expect(await get(true)).toMatchObject({ available: true, handoff: true });
+    expect(await get(false)).toEqual({
+      available: true,
+      handoff: false,
+      downloadUrl: desktopDownloadUrl("darwin"),
+      os: "darwin",
+      installed: false,
+    });
+  });
+
   it("refuses a POST from another site, or through a rebound host name", async () => {
     const { open, post } = server(true);
     const crossSite = { ...STUDIO, origin: "https://evil.example", "sec-fetch-site": "cross-site" };
@@ -67,7 +100,20 @@ describe("open-in-desktop routes", () => {
   it("once live, opens this server's project for Studio's own POST", async () => {
     const { open, post } = server(true);
     expect(await (await post(STUDIO)).json()).toEqual(OPENED);
-    expect(open).toHaveBeenCalledWith("/films/a");
+    expect(open).toHaveBeenCalledWith("/films/a", undefined);
+  });
+
+  it("passes the press's page id on to the hand-off, and drops anything that is not one", async () => {
+    const { open, post } = server(true);
+    const id = "3f2b8c1e-9a4d-4e7b-8c21-5d6e7f8a9b0c";
+    await post(STUDIO, { cta: id });
+    await post(STUDIO, { cta: "../../etc/passwd" });
+    await post(STUDIO, { cta: 42 });
+    expect(open.mock.calls).toEqual([
+      ["/films/a", id],
+      ["/films/a", undefined],
+      ["/films/a", undefined],
+    ]);
   });
 });
 
diff --git a/packages/cli/src/server/desktopRoutes.ts b/packages/cli/src/server/desktopRoutes.ts
index 3aa88df89f..54fc22023e 100644
--- a/packages/cli/src/server/desktopRoutes.ts
+++ b/packages/cli/src/server/desktopRoutes.ts
@@ -7,6 +7,8 @@ import {
 } from "../utils/desktopApp.js";
 import { identityAllowed } from "./telemetryIdentity.js";
 
+const CTA_ID = /^[A-Za-z0-9-]{1,64}$/;
+
 /** A bodiless POST is a simple request, so any page can send one to localhost: it has to come from this Studio. */
 export function sameOriginPost(headers: {
   host?: string;
@@ -19,22 +21,29 @@ export function sameOriginPost(headers: {
   return origin === undefined || origin === `http://${host}`;
 }
 
-/** Edit with Framey's route: whether to show it, where to download, and whether the app takes the project. */
+/** The desktop-app button's route: show it or not, the download, and whether the app here takes the project. */
 export function mountDesktopRoutes(
   app: Hono,
   projectDir: string,
   {
     ready = HANDOFF_READY,
-    open = openInDesktop,
+    open = (dir: string, cta?: string) => openInDesktop(dir, { cta }),
     platform = process.platform,
     installed = () => desktopInstalled({ platform }),
   } = {},
 ): void {
   const downloadUrl = desktopDownloadUrl(platform);
-  app.get("/api/open-in-desktop", (c) =>
-    c.json({ available: downloadUrl !== null || installed(), handoff: ready, downloadUrl }),
-  );
-  app.post("/api/open-in-desktop", (c) => {
+  app.get("/api/open-in-desktop", (c) => {
+    const here = installed();
+    return c.json({
+      available: downloadUrl !== null || here,
+      handoff: ready && here,
+      downloadUrl,
+      os: platform,
+      installed: here,
+    });
+  });
+  app.post("/api/open-in-desktop", async (c) => {
     const allowed = sameOriginPost({
       host: c.req.header("host"),
       origin: c.req.header("origin"),
@@ -47,6 +56,8 @@ export function mountDesktopRoutes(
         reason: "handoff-unavailable",
         downloadUrl,
       });
-    return c.json(open(projectDir));
+    const body: unknown = await c.req.json().catch(() => null);
+    const cta = (body as { cta?: unknown } | null)?.cta;
+    return c.json(open(projectDir, typeof cta === "string" && CTA_ID.test(cta) ? cta : undefined));
   });
 }
diff --git a/packages/cli/src/utils/desktopApp.test.ts b/packages/cli/src/utils/desktopApp.test.ts
index f68639df85..038a6de2be 100644
--- a/packages/cli/src/utils/desktopApp.test.ts
+++ b/packages/cli/src/utils/desktopApp.test.ts
@@ -1,6 +1,15 @@
-import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve, win32 } from "node:path";
+import { isHyperframesProject } from "@hyperframes/core";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { readSeen } from "./appHistory.js";
 import {
@@ -43,6 +52,48 @@ describe("openInDesktop", () => {
     expect(asked).toEqual([`dev.hyperframes.desktop ${FILM}`]);
   });
 
+  it("hands over a folder preview serves from a bare index.html as a project the app accepts", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-bare-"));
+    try {
+      writeFileSync(join(dir, "index.html"), "<html></html>");
+      let marked: boolean | null = null;
+      const result = openInDesktop(dir, {
+        ...LIVE,
+        open: (_id, folder) => ((marked = isHyperframesProject(readdirSync(folder))), true),
+      });
+      expect(result).toMatchObject({ opened: true });
+      expect(marked).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("leaves the press's page id for the app only when the app took the folder", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-cta-"));
+    const record = join(dir, ".hyperframes", "desktop-cta.json");
+    try {
+      writeFileSync(join(dir, "index.html"), "<html></html>");
+      openInDesktop(dir, { ...LIVE, cta: "page-1", open: () => false, installed: () => false });
+      expect(existsSync(record)).toBe(false);
+      openInDesktop(dir, { ...LIVE, cta: "page-1", open: () => true });
+      expect(JSON.parse(readFileSync(record, "utf8"))).toMatchObject({ cta: "page-1" });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("leaves a project's own marker file alone", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-marked-"));
+    try {
+      writeFileSync(join(dir, "index.html"), "<html></html>");
+      writeFileSync(join(dir, "meta.json"), "{}");
+      openInDesktop(dir, { ...LIVE, open: () => true });
+      expect(existsSync(join(dir, "hyperframes.json"))).toBe(false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   it("falls back to Canary when only Canary is installed", () => {
     const result = openInDesktop(FILM, { ...LIVE, open: (id) => id.endsWith(".canary") });
     expect(result).toMatchObject({ opened: true, app: "HyperFrames Canary" });
diff --git a/packages/cli/src/utils/desktopApp.ts b/packages/cli/src/utils/desktopApp.ts
index 75d7d49eba..36753756b3 100644
--- a/packages/cli/src/utils/desktopApp.ts
+++ b/packages/cli/src/utils/desktopApp.ts
@@ -1,8 +1,10 @@
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, isAbsolute, join, relative, win32 } from "node:path";
+import { isHyperframesProject } from "@hyperframes/core";
 import { addCatchUpNote, markSeen, readSeen } from "./appHistory.js";
+import { createProjectConfig } from "./projectConfig.js";
 import { writeRecord } from "./projectRecords.js";
 
 // The HyperFrames desktop app (not "Studio"): `open -b` on macOS, its executable elsewhere; released, then Canary.
@@ -32,6 +34,8 @@ export interface AgentSession {
 }
 
 export const AGENT_HANDOFF_FILE = join(".hyperframes", "agent-handoff.json");
+/** The Studio page's telemetry `tab_id`, left for the app to report its first open and export against. */
+const DESKTOP_CTA_RECORD = "desktop-cta.json";
 
 // ponytail: Claude Code, then Codex, then Grok; an agent started inside another's shell carries both, unsorted.
 export function agentSession(env: NodeJS.ProcessEnv = process.env): AgentSession | null {
@@ -131,6 +135,17 @@ function leaveHandoff(dir: string, session: AgentSession | null): AgentSession |
   return session;
 }
 
+function markBareIndexAsProject(dir: string): void {
+  try {
+    if (existsSync(join(dir, "index.html")) && !isHyperframesProject(readdirSync(dir)))
+      createProjectConfig(dir);
+  } catch (error) {
+    console.warn(
+      `◇  Couldn't add hyperframes.json to ${dir}, so the app may not open it: ${error}`,
+    );
+  }
+}
+
 // ponytail: success on Windows and Linux means the spawn started, not that the app took the folder; wait for the
 // app's own acknowledgement if a broken install ever needs reporting.
 export function openInDesktop(
@@ -142,8 +157,10 @@ export function openInDesktop(
     launch = launchApp,
     installed = () => desktopInstalled({ platform }),
     env = process.env,
+    cta,
     ...where
   }: AppLookup & {
+    cta?: string;
     ready?: boolean;
     open?: (bundleId: string, dir: string) => boolean;
     launch?: (executable: string, dir: string) => boolean;
@@ -157,12 +174,16 @@ export function openInDesktop(
     reason,
     downloadUrl: desktopDownloadUrl(platform) ?? STUDIO_PAGE,
   });
-  const opened = (canary: boolean): DesktopOpenResult => ({
-    opened: true,
-    app: canary ? "HyperFrames Canary" : "the HyperFrames desktop app",
-    handedOver: leaveHandoff(dir, agentSession(env)),
-  });
+  const opened = (canary: boolean): DesktopOpenResult => {
+    if (cta) writeRecord(dir, DESKTOP_CTA_RECORD, JSON.stringify({ cta, at: Date.now() }));
+    return {
+      opened: true,
+      app: canary ? "HyperFrames Canary" : "the HyperFrames desktop app",
+      handedOver: leaveHandoff(dir, agentSession(env)),
+    };
+  };
   if (!ready) return notOpened("handoff-unavailable");
+  markBareIndexAsProject(dir);
   if (platform === "darwin") {
     const bundleId = DESKTOP_BUNDLE_IDS.find((id) => open(id, dir));
     if (!bundleId) return notOpened(installed() ? "open-failed" : "not-installed");
diff --git a/packages/studio/src/components/DesktopGuideCard.tsx b/packages/studio/src/components/DesktopGuideCard.tsx
new file mode 100644
index 0000000000..cc5c76dfde
--- /dev/null
+++ b/packages/studio/src/components/DesktopGuideCard.tsx
@@ -0,0 +1,292 @@
+import { ArrowSquareOut, Check, Copy } from "@phosphor-icons/react";
+import { useEffect, useState, type ReactNode } from "react";
+import { copyTextToClipboard } from "../utils/clipboard";
+import { FrameyGlyph, type FrameyMood } from "./FrameyGlyph";
+import { Button, cn } from "./ui";
+
+// The desktop-app guide card under OpenInDesktopButton: Framey and three steps (download, install, open), all drawn
+// from one `Progress`.
+
+export type DesktopRoute = {
+  handoff: boolean;
+  downloadUrl: string | null;
+  context: { os: string; app_installed: boolean; download_available: boolean };
+};
+
+/** The OS for the download, and what "this …" calls the machine. */
+const platformName = (os: string): string =>
+  os === "darwin" ? "Mac" : os === "linux" ? "Linux" : "your computer";
+const deviceName = (os: string): string => (os === "darwin" ? "Mac" : "computer");
+
+const NOTE = "mt-0.5 text-step-12 text-text-2 text-pretty";
+
+/** Re-keys on `value`, so text that changes settles in rather than snapping. */
+export function Swap({ value, children }: { value: string; children: ReactNode }) {
+  return (
+    <span key={value} className="hf-guide-swap inline-block">
+      {children}
+    </span>
+  );
+}
+
+type StepState = "todo" | "now" | "done" | "bad";
+const TODO: StepState = "todo";
+const NOW: StepState = "now";
+const DONE: StepState = "done";
+const BAD: StepState = "bad";
+
+function Step({
+  n,
+  state,
+  title,
+  children,
+}: {
+  n: number;
+  state: StepState;
+  title: string;
+  children: ReactNode;
+}) {
+  return (
+    <li
+      className="grid grid-cols-[22px_minmax(0,1fr)] gap-2.5 border-border py-2 not-first:border-t"
+      data-step={n}
+      data-state={state}
+    >
+      <span
+        className={cn(
+          "grid size-[22px] place-items-center rounded-full text-step-11 font-bold tabular-nums",
+          state === "now" && "bg-accent text-on-accent shadow-[0_0_0_3px_var(--color-on)]",
+          state === "done" && "bg-on text-accent-ink",
+          state === "bad" && "bg-danger/15 text-danger-ink",
+          state === "todo" && "bg-hover text-text-2",
+        )}
+      >
+        {state === "done" ? <Check size={12} weight="bold" className="hf-guide-tick" /> : n}
+      </span>
+      <div className="min-w-0">
+        <b
+          title={title}
+          className={cn(
+            "block truncate text-step-13 font-semibold",
+            state === "todo" ? "text-text-muted" : "text-text-0",
+          )}
+        >
+          {title}
+        </b>
+        {children}
+      </div>
+    </li>
+  );
+}
+
+function Spinner() {
+  return (
+    <span
+      aria-hidden="true"
+      className="size-3 shrink-0 animate-spin rounded-full border-2 border-on-hover border-t-accent motion-reduce:animate-none"
+    />
+  );
+}
+
+/** The project folder, with a copy control that confirms for a moment. */
+function FolderPath({ dir }: { dir: string }) {
+  const [copied, setCopied] = useState(false);
+  useEffect(() => {
+    if (!copied) return;
+    const timer = setTimeout(() => setCopied(false), 1500);
+    return () => clearTimeout(timer);
+  }, [copied]);
+  return (
+    <div className="mt-1.5 flex min-w-0 items-center gap-1.5">
+      <span
+        title={dir}
+        data-testid="desktop-guide-folder"
+        className="min-w-0 flex-1 truncate rounded-md border border-border bg-bg-0 px-2 py-1.5 font-mono text-step-11 text-text-0"
+      >
+        {dir}
+      </span>
+      <Button
+        variant="secondary"
+        aria-label={copied ? "Copied" : "Copy folder path"}
+        className="w-ctl px-0"
+        onClick={() => void copyTextToClipboard(dir).then((ok) => ok && setCopied(true))}
+      >
+        {copied ? <Check size={14} className="hf-guide-tick" /> : <Copy size={14} />}
+      </Button>
+    </div>
+  );
+}
+
+/** Where the person is: what the button says, how Framey looks, and each step's state all derive from this. */
+export type Progress = {
+  route: DesktopRoute;
+  opening: boolean;
+  failed: boolean;
+  downloaded: boolean;
+  slow: boolean;
+  /** The app turned up on this page (not already there): Framey hops once. */
+  arrived: boolean;
+};
+
+const isInstalled = (p: Progress) => p.route.context.app_installed;
+export const isWaiting = (p: Progress) => p.downloaded && !isInstalled(p);
+
+export function moodOf(p: Progress): FrameyMood {
+  if (p.opening) return "opening";
+  if (p.failed) return "error";
+  if (isWaiting(p)) return "thinking";
+  return p.arrived ? "found" : "idle";
+}
+
+export function labelOf(p: Progress): string {
+  if (p.opening) return "Opening in the app…";
+  if (p.failed) return "Couldn't open";
+  if (p.route.handoff) return "Open in desktop app";
+  return isWaiting(p) ? "Finish installing" : "Install the desktop app";
+}
+
+function subtitleOf(p: Progress): string {
+  if (p.failed) return "Almost there: the last step needs another try.";
+  if (!isInstalled(p))
+    return "Watch it, click a frame, tell Framey what to change. Three steps, about two minutes.";
+  return p.route.handoff
+    ? "Everything is ready. One press and you're in."
+    : "Almost there: one last step.";
+}
+
+type CardProps = {
+  progress: Progress;
+  projectDir: string | null;
+  onDownload: () => void;
+  onOpen: () => void;
+};
+
+function DownloadStep({ progress, onDownload }: CardProps) {
+  const { context, downloadUrl } = progress.route;
+  const where = platformName(context.os);
+  const installed = isInstalled(progress);
+  if (!progress.downloaded && !installed)
+    return (
+      <Step n={1} state={NOW} title={`Download HyperFrames for ${where}`}>
+        <p className={NOTE}>Free. Opens hyperframes.dev in a new tab.</p>
+        <Button
+          variant="primary"
+          className="mt-2"
+          icon={<ArrowSquareOut size={14} />}
+          onClick={onDownload}
+        >
+          Download for {where}
+        </Button>
+      </Step>
+    );
+  return (
+    <Step n={1} state={DONE} title={`Download HyperFrames for ${where}`}>
+      <p className={NOTE}>
+        {installed ? `Already on this ${deviceName(context.os)}.` : "Started in your browser."}
+        {!installed && downloadUrl && (
+          <button
+            type="button"
+            className="ml-1.5 cursor-pointer font-medium text-accent-ink hover:underline"
+            onClick={onDownload}
+          >
+            Download again
+          </button>
+        )}
+      </p>
+    </Step>
+  );
+}
+
+function InstallStep({ progress }: CardProps) {
+  const { os } = progress.route.context;
+  if (isInstalled(progress))
+    return (
+      <Step n={2} state={DONE} title="Install it">
+        <p className={NOTE}>
+          <Swap value="found">Found HyperFrames on this {deviceName(os)}.</Swap>
+        </p>
+      </Step>
+    );
+  return (
+    <Step n={2} state={progress.downloaded ? NOW : TODO} title="Install it">
+      <p className={NOTE}>
+        {os === "darwin"
+          ? "Open the download and drag HyperFrames into Applications."
+          : "Open the download to install HyperFrames."}
+      </p>
+      {progress.downloaded && (
+        <p className="mt-1.5 flex items-center gap-2 text-step-12 text-text-2" role="status">
+          <Spinner />
+          <Swap value={String(progress.slow)}>
+            {progress.slow ? "Still looking. Did the download finish?" : "Looking for the app…"}
+          </Swap>
+        </p>
+      )}
+    </Step>
+  );
+}
+
+function OpenStep({ progress, projectDir, onOpen }: CardProps) {
+  const title = `Open ${projectDir?.split(/[\\/]/).filter(Boolean).pop() ?? "this project"}`;
+  const folder = projectDir && <FolderPath dir={projectDir} />;
+  if (progress.failed)
+    return (
+      <Step n={3} state={BAD} title={title}>
+        <p className={NOTE}>
+          The app didn't start. Try again, or open HyperFrames and drop this folder in:
+        </p>
+        {folder}
+        <Button variant="primary" className="mt-2" loading={progress.opening} onClick={onOpen}>
+          Try again
+        </Button>
+      </Step>
+    );
+  const installed = isInstalled(progress);
+  // Installed, but this platform's app cannot take a handed-over project yet: the folder is the way in.
+  if (installed && !progress.route.handoff)
+    return (
+      <Step n={3} state={NOW} title={title}>
+        <p className={NOTE}>Open HyperFrames and drop this folder in:</p>
+        {folder}
+      </Step>
+    );
+  return (
+    <Step n={3} state={installed ? NOW : TODO} title={title}>
+      <p className={NOTE}>Same project, same files, in the desktop app.</p>
+      <Button
+        variant="primary"
+        className="mt-2"
+        disabled={!progress.route.handoff}
+        loading={progress.opening}
+        onClick={onOpen}
+      >
+        Open in desktop app
+      </Button>
+    </Step>
+  );
+}
+
+export function GuideCard(props: CardProps) {
+  const { progress } = props;
+  const subtitle = subtitleOf(progress);
+  return (
+    <div data-testid="desktop-guide">
+      <div className="grid grid-cols-[auto_minmax(0,1fr)] items-center gap-3 bg-linear-to-b from-accent/8 to-transparent px-4 pt-4 pb-3">
+        <FrameyGlyph size={46} mood={moodOf(progress)} />
+        <div className="min-w-0">
+          <p className="text-step-14 font-semibold text-balance text-text-0">
+            Edit this video in the desktop app
+          </p>
+          <p className={NOTE}>
+            <Swap value={subtitle}>{subtitle}</Swap>
+          </p>
+        </div>
+      </div>
+      <ol className="m-0 grid list-none px-4 pt-1 pb-4">
+        <DownloadStep {...props} />
+        <InstallStep {...props} />
+        <OpenStep {...props} />
+      </ol>
+    </div>
+  );
+}
diff --git a/packages/studio/src/components/FrameyGlyph.tsx b/packages/studio/src/components/FrameyGlyph.tsx
index abcde5f219..f11cad15e6 100644
--- a/packages/studio/src/components/FrameyGlyph.tsx
+++ b/packages/studio/src/components/FrameyGlyph.tsx
@@ -1,51 +1,101 @@
 import type { Ref } from "react";
+import { cn } from "./ui";
 
-// Framey, the desktop app's cursor mascot, as hyperframes-internal packages/nib draws it: a rounded triangle with a
-// white rim and one eye. The viewBox frames the body with its rim; the tip points up and left like a cursor.
+// Framey, the desktop app's cursor mascot, as the app draws it: a rounded triangle with a white rim and one eye,
+// framed square around the body and rim.
 const BODY = "M77.55 48.44 L122.77 65.85 L99.3 89.41 Z";
 const EYE = { cx: 111.6, cy: 68.2, r: 11.5 };
+const RIM = 24;
+const VIEW_BOX = "65.55 34.315 69.22 69.22";
 
-/** `eyeRef` moves the pupils (a translate of a few px) without re-rendering. */
+/** The app's moods: what Framey's eye and body do (styles in components.css, `.hf-framey-mood`). */
+export type FrameyMood = "idle" | "thinking" | "found" | "opening" | "error";
+
+const INK = "var(--color-framey-ink)";
+
+function Pupils({ mood }: { mood?: FrameyMood }) {
+  const { cx, cy } = EYE;
+  if (mood === "found")
+    return (
+      <g transform={`translate(${cx + 1.7} ${cy - 2.3})`}>
+        <circle r={4.6} fill={INK} />
+        <circle cx={1.4} cy={-1.6} r={1.3} fill="var(--color-white)" />
+      </g>
+    );
+  if (mood === "thinking")
+    return (
+      <g transform={`translate(${cx} ${cy})`}>
+        <g className="hf-framey-orbit">
+          <circle cx={-2.8} r={1.9} fill={INK} />
+          <circle cx={2.8} r={1.9} fill={INK} />
+        </g>
+      </g>
+    );
+  if (mood === "error")
+    return (
+      <path
+        transform={`translate(${cx} ${cy})`}
+        d="M-5 -2 L-1.4 1.6 M-1.4 -2 L-5 1.6 M1.4 -2 L5 1.6 M5 -2 L1.4 1.6"
+        stroke={INK}
+        strokeWidth={1.7}
+        strokeLinecap="round"
+      />
+    );
+  return (
+    <path
+      d={`M${cx - 2.6} ${cy - 2.4} V${cy + 2.4} M${cx + 2.6} ${cy - 2.4} V${cy + 2.4}`}
+      stroke={INK}
+      strokeWidth={2.4}
+      strokeLinecap="round"
+    />
+  );
+}
+
+/** `eyeRef` moves the pupils (a translate of a few px) without re-rendering. Without `mood` Framey holds still. */
 export function FrameyGlyph({
   size,
   className,
   eyeRef,
+  mood,
 }: {
   size: number;
   className?: string;
   eyeRef?: Ref<SVGGElement>;
+  mood?: FrameyMood;
 }) {
   return (
     <svg
       width={size}
       height={size}
-      viewBox="58 30 82 76"
+      viewBox={VIEW_BOX}
       aria-hidden="true"
-      className={className}
       overflow="visible"
+      className={cn(mood && "hf-framey-mood", className)}
+      data-mood={mood}
     >
-      <path
-        d={BODY}
-        fill="var(--color-white)"
-        stroke="var(--color-white)"
-        strokeWidth={24}
-        strokeLinejoin="round"
-      />
-      <path
-        d={BODY}
-        fill="var(--color-framey)"
-        stroke="var(--color-framey)"
-        strokeWidth={19}
-        strokeLinejoin="round"
-      />
-      <circle cx={EYE.cx} cy={EYE.cy} r={EYE.r} fill="var(--color-white)" />
-      <g ref={eyeRef} className="hf-framey-eye">
-        <path
-          d={`M${EYE.cx - 2.6} ${EYE.cy - 2} V${EYE.cy + 2} M${EYE.cx + 2.6} ${EYE.cy - 2} V${EYE.cy + 2}`}
-          stroke="var(--color-framey-ink)"
-          strokeWidth={2.4}
-          strokeLinecap="round"
-        />
+      <g className="hf-framey-whole">
+        <g className="hf-framey-body">
+          <path
+            d={BODY}
+            fill="var(--color-white)"
+            stroke="var(--color-white)"
+            strokeWidth={RIM}
+            strokeLinejoin="round"
+          />
+          <path
+            d={BODY}
+            fill="var(--color-framey)"
+            stroke="var(--color-framey)"
+            strokeWidth={19}
+            strokeLinejoin="round"
+          />
+          <g className="hf-framey-lid">
+            <circle cx={EYE.cx} cy={EYE.cy} r={EYE.r} fill="var(--color-white)" />
+            <g ref={eyeRef} className="hf-framey-eye">
+              <Pupils mood={mood} />
+            </g>
+          </g>
+        </g>
       </g>
     </svg>
   );
diff --git a/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx b/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx
index 9dc4fae2f3..7dfc264655 100644
--- a/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx
+++ b/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx
@@ -1,8 +1,8 @@
 // @vitest-environment happy-dom
 
 /**
- * "Edit with Framey": shown where the preview server has the app or its download to offer; a press opens the project in the app,
- * or introduces Framey with the download while the app cannot take it or is missing.
+ * "Install the desktop app": shown where the preview server has the app or its download to offer. With the app ready a
+ * press opens the project in it; otherwise it opens the guide card (download, install, open).
  */
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
@@ -12,21 +12,39 @@ import { afterEach, beforeEach, expect, it, vi } from "vitest";
 
 const showToast = vi.fn();
 vi.mock("../contexts/StudioContext", () => ({ useStudioShellContext: () => ({ showToast }) }));
-vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+const track = vi.fn();
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: track }));
+const FOLDER = "/work/launch-teaser";
+vi.mock("../contexts/FileManagerContext", () => ({
+  useFileManagerContextOptional: () => ({ projectDir: FOLDER }),
+}));
+const copied: string[] = [];
+vi.mock("../utils/clipboard", () => ({
+  copyTextToClipboard: async (text: string) => (copied.push(text), true),
+}));
 
 const { OpenInDesktopButton } = await import("./OpenInDesktopButton");
+const { resolveTabId } = await import("../telemetry/tabId");
+const tagged = (url: string) => {
+  const withId = new URL(url);
+  withId.searchParams.set("hf_cta", resolveTabId());
+  return withId.toString();
+};
 
 const DOWNLOAD = "https://hyperframes.dev/studio/download";
 let mounted: { root: Root; host: HTMLElement } | null = null;
 let posts: number;
+let postBodies: unknown[];
 
 function serve(get: Response | null, post?: unknown) {
   posts = 0;
+  postBodies = [];
   vi.stubGlobal(
     "fetch",
     vi.fn(async (_url: string, init?: RequestInit) => {
       if (init?.method === "POST") {
         posts += 1;
+        postBodies.push(JSON.parse(String(init.body ?? "null")));
         return Response.json(post);
       }
       return get ?? new Response("Not found", { status: 404 });
@@ -43,15 +61,32 @@ async function mount(): Promise<HTMLElement> {
   return host;
 }
 
-const downloadHref = () =>
-  [...document.querySelectorAll("a")]
-    .find((a) => a.textContent?.includes("Get the desktop app"))
-    ?.getAttribute("href");
-
 const button = () =>
   document.querySelector<HTMLButtonElement>('[data-testid="header-open-in-desktop"]');
 
-beforeEach(() => showToast.mockReset());
+let reveal: (() => void) | null = null;
+
+beforeEach(() => {
+  showToast.mockReset();
+  track.mockReset();
+  reveal = null;
+  vi.stubGlobal(
+    "IntersectionObserver",
+    class {
+      constructor(private readonly onChange: (entries: { isIntersecting: boolean }[]) => void) {}
+      observe() {
+        reveal = () => this.onChange([{ isIntersecting: true }]);
+      }
+      disconnect() {
+        reveal = null;
+      }
+    },
+  );
+});
+
+const events = (name: string) =>
+  track.mock.calls.filter(([event]) => event === name).map(([, props]) => props);
+const MAC = { os: "darwin", app_installed: true, download_available: true };
 
 afterEach(() => {
   vi.unstubAllGlobals();
@@ -90,16 +125,186 @@ it("opens the project in an installed app that has no download (Windows)", async
   expect(posts).toBe(1);
 });
 
-it("while the app cannot take a project yet, introduces Framey with the download and opens nothing", async () => {
-  const linux = `${DOWNLOAD}?os=linux`;
-  serve(Response.json({ available: true, handoff: false, downloadUrl: linux }), { opened: true });
+/** Runs `body` with the poll and slow-download timers under test control. */
+async function withFakeTimers(body: () => Promise<void>) {
+  vi.useFakeTimers({ toFake: ["setInterval", "clearInterval", "setTimeout", "clearTimeout"] });
+  try {
+    await body();
+  } finally {
+    vi.useRealTimers();
+  }
+}
+
+const guide = () => document.querySelector<HTMLElement>('[data-testid="desktop-guide"]');
+const stepState = (n: number) =>
+  guide()?.querySelector<HTMLElement>(`[data-step="${n}"]`)?.dataset.state ?? null;
+const cardButton = (text: string) =>
+  [...(guide()?.querySelectorAll("button") ?? [])].find((b) => b.textContent === text) ?? null;
+const noApp = { os: "darwin", app_installed: false, download_available: true };
+const routeBody = (over: Record<string, unknown> = {}) => ({
+  ...noApp,
+  available: true,
+  handoff: false,
+  downloadUrl: DOWNLOAD,
+  installed: false,
+  ...over,
+});
+
+it("reads 'Install the desktop app' beside Framey, and 'Open in desktop app' once the app takes projects", async () => {
+  serve(Response.json(routeBody()));
+  await mount();
+  expect(button()!.textContent).toBe("Install the desktop app");
+  expect(button()!.querySelector("svg .hf-framey-eye")).not.toBeNull();
+  act(() => mounted!.root.unmount());
+  mounted = null;
+
+  serve(Response.json(routeBody({ handoff: true, installed: true, app_installed: true })));
+  await mount();
+  expect(button()!.textContent).toBe("Open in desktop app");
+});
+
+it("without the app, a press opens the guide at step 1 and hands nothing over", async () => {
+  serve(Response.json(routeBody()), { opened: true });
   await mount();
   await act(async () => button()!.click());
+  expect(guide()).not.toBeNull();
+  expect([stepState(1), stepState(2), stepState(3)]).toEqual(["now", "todo", "todo"]);
+  expect(cardButton("Open in desktop app")!.disabled).toBe(true);
   expect(posts).toBe(0);
-  expect(document.body.textContent).toContain("Meet Framey");
-  expect(downloadHref()).toBe(linux);
+  expect(events("desktop_cta_guide")).toEqual([{ step: "opened", ...noApp }]);
 });
 
+it("step 1 opens the tagged download in a new tab, then the button says what is left", async () => {
+  const opened: string[] = [];
+  const tab = { opener: {} as unknown };
+  vi.stubGlobal("open", (url: string) => (opened.push(url), tab));
+  serve(Response.json(routeBody()));
+  await mount();
+  await act(async () => button()!.click());
+  await act(async () => cardButton("Download for Mac")!.click());
+  expect(opened).toEqual([tagged(DOWNLOAD)]);
+  expect(tab.opener).toBeNull();
+  expect([stepState(1), stepState(2)]).toEqual(["done", "now"]);
+  expect(guide()!.textContent).toContain("Looking for the app…");
+  expect(button()!.textContent).toBe("Finish installing2 of 3");
+  expect(events("desktop_cta_outcome")).toEqual([{ outcome: "sent_to_download", ...noApp }]);
+  expect(events("desktop_cta_guide").map((e) => (e as { step: string }).step)).toEqual([
+    "opened",
+    "download_opened",
+  ]);
+});
+
+it("names the download when the browser blocks the new tab, and leaves step 1 to do", async () => {
+  vi.stubGlobal("open", () => null);
+  serve(Response.json(routeBody()));
+  await mount();
+  await act(async () => button()!.click());
+  await act(async () => cardButton("Download for Mac")!.click());
+  expect(showToast).toHaveBeenCalledWith(`Get the HyperFrames desktop app at ${DOWNLOAD}`, "info");
+  expect(stepState(1)).toBe("now");
+  expect(events("desktop_cta_outcome")).toEqual([
+    { outcome: "failed", reason: "download_tab_blocked", ...noApp },
+  ]);
+});
+
+it("finds the install only from the preview server, asking only while the card is open", () =>
+  withFakeTimers(async () => {
+    let answer = routeBody();
+    let gets = 0;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (_url: string, init?: RequestInit) => {
+        if (init?.method === "POST") return Response.json({ opened: true });
+        gets += 1;
+        return Response.json(answer);
+      }),
+    );
+    vi.stubGlobal("open", () => ({ opener: null }));
+    await mount();
+    expect(gets).toBe(1);
+    await act(async () => vi.advanceTimersByTime(10_000));
+    expect(gets).toBe(1);
+
+    await act(async () => button()!.click());
+    await act(async () => cardButton("Download for Mac")!.click());
+    await act(async () => vi.advanceTimersByTime(2000));
+    const asked = gets;
+    expect(asked).toBeGreaterThan(1);
+    expect(events("desktop_cta_guide").map((e) => (e as { step: string }).step)).not.toContain(
+      "install_detected",
+    );
+
+    answer = routeBody({ handoff: true, installed: true });
+    await act(async () => vi.advanceTimersByTime(2000));
+    expect([stepState(2), stepState(3)]).toEqual(["done", "now"]);
+    expect(cardButton("Open in desktop app")!.disabled).toBe(false);
+    expect(button()!.textContent).toBe("Open in desktop app");
+    expect(guide()!.querySelector('svg[data-mood="found"]')).not.toBeNull();
+    const detected = events("desktop_cta_guide").filter(
+      (e) => (e as { step: string }).step === "install_detected",
+    );
+    expect(detected).toEqual([
+      { step: "install_detected", os: "darwin", app_installed: true, download_available: true },
+    ]);
+    const settled = gets;
+    await act(async () => vi.advanceTimersByTime(10_000));
+    expect(gets).toBe(settled);
+  }));
+
+it("records the install once per page, even when the app goes and comes back", () =>
+  withFakeTimers(async () => {
+    let answer = routeBody();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (_url: string, init?: RequestInit) => {
+        if (init?.method === "POST")
+          return Response.json({ opened: false, reason: "not-installed", downloadUrl: DOWNLOAD });
+        return Response.json(answer);
+      }),
+    );
+    await mount();
+    await act(async () => button()!.click());
+    answer = routeBody({ handoff: true, installed: true });
+    await act(async () => vi.advanceTimersByTime(2000));
+    expect(stepState(2)).toBe("done");
+
+    // The app is removed: the hand-off finds it gone, and the server stops reporting it.
+    answer = routeBody();
+    await act(async () => cardButton("Open in desktop app")!.click());
+    expect(stepState(2)).toBe("todo");
+    // Installed again: the card finds it a second time.
+    answer = routeBody({ handoff: true, installed: true });
+    await act(async () => vi.advanceTimersByTime(2000));
+    expect(stepState(2)).toBe("done");
+
+    const detected = events("desktop_cta_guide").filter(
+      (e) => (e as { step: string }).step === "install_detected",
+    );
+    expect(detected).toHaveLength(1);
+  }));
+
+it("stops asking the preview server when the card closes", () =>
+  withFakeTimers(async () => {
+    let gets = 0;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ((gets += 1), Response.json(routeBody()))),
+    );
+    await mount();
+    await act(async () => button()!.click());
+    await act(async () => vi.advanceTimersByTime(4000));
+    expect(gets).toBeGreaterThan(2);
+    await act(async () => button()!.click());
+    expect(guide()).toBeNull();
+    const closedAt = gets;
+    await act(async () => vi.advanceTimersByTime(10_000));
+    expect(gets).toBe(closedAt);
+    expect(events("desktop_cta_guide").map((e) => (e as { step: string }).step)).toEqual([
+      "opened",
+      "closed",
+    ]);
+  }));
+
 it("opens the project in the app and says so", async () => {
   serve(Response.json({ available: true, handoff: true, downloadUrl: DOWNLOAD }), {
     opened: true,
@@ -108,23 +313,200 @@ it("opens the project in the app and says so", async () => {
   await mount();
   await act(async () => button()!.click());
   expect(posts).toBe(1);
+  expect(postBodies).toEqual([{ cta: resolveTabId() }]);
+  expect(guide()).toBeNull();
   expect(showToast).toHaveBeenCalledWith(
-    "Framey is opening this project in the HyperFrames desktop app",
+    "Opening this project in the HyperFrames desktop app",
     "info",
   );
   expect(button()!.dataset.opening).toBe("true");
-  expect(document.body.textContent).not.toContain("Meet Framey");
 });
 
-it("introduces Framey and offers the download when the app is missing", async () => {
-  serve(Response.json({ available: true, handoff: true, downloadUrl: DOWNLOAD }), {
+it("a failed hand-off opens the card at step 3 with the folder to copy and Try again", async () => {
+  const opened: string[] = [];
+  vi.stubGlobal("open", (url: string) => (opened.push(url), {}));
+  copied.length = 0;
+  serve(Response.json(routeBody({ handoff: true, installed: true })), {
+    opened: false,
+    reason: "open-failed",
+    downloadUrl: DOWNLOAD,
+  });
+  await mount();
+  await act(async () => button()!.click());
+  expect(opened).toEqual([]);
+  expect(button()!.textContent).toBe("Couldn't open");
+  expect(stepState(3)).toBe("bad");
+  expect(guide()!.textContent).toContain("Almost there: the last step needs another try.");
+  expect(guide()!.textContent).not.toContain("Everything is ready");
+  expect(guide()!.querySelector('[data-testid="desktop-guide-folder"]')!.textContent).toBe(FOLDER);
+  await act(async () =>
+    guide()!.querySelector<HTMLButtonElement>('[aria-label="Copy folder path"]')!.click(),
+  );
+  expect(copied).toEqual([FOLDER]);
+  await act(async () => cardButton("Try again")!.click());
+  expect(posts).toBe(2);
+});
+
+it("a hand-off that finds the app gone goes back to the download step", async () => {
+  serve(Response.json(routeBody({ handoff: true, installed: true })), {
     opened: false,
     reason: "not-installed",
     downloadUrl: DOWNLOAD,
   });
   await mount();
   await act(async () => button()!.click());
-  expect(showToast).not.toHaveBeenCalled();
-  expect(document.body.textContent).toContain("Meet Framey");
-  expect(downloadHref()).toBe(DOWNLOAD);
+  expect([stepState(1), stepState(3)]).toEqual(["now", "todo"]);
+  expect(button()!.textContent).toBe("Install the desktop app");
+});
+
+it("where the app is installed but cannot take a project (Linux), step 3 shows the folder to drop in", async () => {
+  const linux = { os: "linux", app_installed: true, download_available: true };
+  serve(
+    Response.json({
+      ...linux,
+      available: true,
+      handoff: false,
+      downloadUrl: `${DOWNLOAD}?os=linux`,
+      installed: true,
+    }),
+    { opened: true },
+  );
+  await mount();
+  await act(async () => button()!.click());
+  expect([stepState(1), stepState(2), stepState(3)]).toEqual(["done", "done", "now"]);
+  expect(guide()!.textContent).toContain("Found HyperFrames on this computer.");
+  expect(guide()!.textContent).toContain("Open HyperFrames and drop this folder in:");
+  expect(guide()!.querySelector('[data-testid="desktop-guide-folder"]')!.textContent).toBe(FOLDER);
+  expect(cardButton("Open in desktop app")).toBeNull();
+  expect(posts).toBe(0);
+});
+
+it("counts where the button can show, the app here, and platforms with no app", async () => {
+  serve(
+    Response.json({
+      ...MAC,
+      available: true,
+      handoff: true,
+      downloadUrl: DOWNLOAD,
+      installed: true,
+    }),
+  );
+  await mount();
+  expect(events("desktop_cta_eligibility")).toEqual([{ eligibility: "open_in_app", ...MAC }]);
+  act(() => mounted!.root.unmount());
+  mounted = null;
+
+  track.mockReset();
+  serve(
+    Response.json({
+      available: false,
+      handoff: false,
+      downloadUrl: null,
+      os: "win32",
+      installed: false,
+    }),
+  );
+  await mount();
+  expect(button()).toBeNull();
+  expect(events("desktop_cta_eligibility")).toEqual([
+    {
+      eligibility: "no_app_for_platform",
+      os: "win32",
+      app_installed: false,
+      download_available: false,
+    },
+  ]);
+  expect(events("desktop_cta_impression")).toEqual([]);
+});
+
+it("records one impression, only once the button is on screen", async () => {
+  serve(
+    Response.json({
+      ...MAC,
+      available: true,
+      handoff: true,
+      downloadUrl: DOWNLOAD,
+      installed: true,
+    }),
+  );
+  await mount();
+  expect(events("desktop_cta_impression")).toEqual([]);
+  act(() => reveal!());
+  expect(events("desktop_cta_impression")).toEqual([{ eligibility: "open_in_app", ...MAC }]);
+  expect(reveal).toBeNull();
+});
+
+it("records the click and its outcome for each way a hand-off ends", async () => {
+  const outcomes = async (post: unknown) => {
+    track.mockReset();
+    serve(
+      Response.json({
+        ...MAC,
+        available: true,
+        handoff: true,
+        downloadUrl: DOWNLOAD,
+        installed: true,
+      }),
+      post,
+    );
+    await mount();
+    await act(async () => button()!.click());
+    const result = { clicks: events("toolbar_action"), outcomes: events("desktop_cta_outcome") };
+    act(() => mounted!.root.unmount());
+    mounted = null;
+    return result;
+  };
+  expect(await outcomes({ opened: true })).toEqual({
+    clicks: [{ action: "open_in_desktop", ...MAC }],
+    outcomes: [{ outcome: "opened", ...MAC }],
+  });
+  expect(
+    (await outcomes({ opened: false, reason: "open-failed", downloadUrl: DOWNLOAD })).outcomes,
+  ).toEqual([{ outcome: "failed", reason: "open-failed", ...MAC }]);
+  expect(
+    (await outcomes({ opened: false, reason: "not-installed", downloadUrl: DOWNLOAD })).outcomes,
+  ).toEqual([{ outcome: "failed", reason: "not-installed", ...MAC }]);
+});
+
+it("records a press the preview server never answered as failed", async () => {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (_url: string, init?: RequestInit) => {
+      if (init?.method === "POST") throw new TypeError("network");
+      return Response.json({
+        ...MAC,
+        available: true,
+        handoff: true,
+        downloadUrl: DOWNLOAD,
+        installed: true,
+      });
+    }),
+  );
+  await mount();
+  await act(async () => button()!.click());
+  expect(events("desktop_cta_outcome")).toEqual([
+    { outcome: "failed", reason: "preview_server_unreachable", ...MAC },
+  ]);
+});
+
+it("records the download press as sent to the download, never as an install", async () => {
+  const linux = { os: "linux", app_installed: false, download_available: true };
+  vi.stubGlobal("open", () => ({ opener: null }));
+  serve(
+    Response.json({
+      ...linux,
+      available: true,
+      handoff: false,
+      downloadUrl: `${DOWNLOAD}?os=linux`,
+      installed: false,
+    }),
+  );
+  await mount();
+  await act(async () => button()!.click());
+  await act(async () => cardButton("Download for Linux")!.click());
+  expect(events("toolbar_action")).toEqual([{ action: "get_desktop_app", ...linux }]);
+  expect(events("desktop_cta_outcome")).toEqual([{ outcome: "sent_to_download", ...linux }]);
+  const sent = JSON.stringify(track.mock.calls);
+  expect(sent).not.toMatch(/"(outcome|step)":"[a-z_]*install/);
+  expect(sent).not.toContain("/");
 });
diff --git a/packages/studio/src/components/OpenInDesktopButton.tsx b/packages/studio/src/components/OpenInDesktopButton.tsx
index 22d2f32411..37a4aa874e 100644
--- a/packages/studio/src/components/OpenInDesktopButton.tsx
+++ b/packages/studio/src/components/OpenInDesktopButton.tsx
@@ -1,41 +1,121 @@
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { useStudioShellContext } from "../contexts/StudioContext";
+import { useFileManagerContextOptional } from "../contexts/FileManagerContext";
+import { resolveTabId } from "../telemetry/tabId";
 import { studioApiFetch } from "../utils/studioApiFetch";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import {
+  GuideCard,
+  Swap,
+  isWaiting,
+  labelOf,
+  moodOf,
+  type DesktopRoute,
+  type Progress,
+} from "./DesktopGuideCard";
 import { FrameyGlyph } from "./FrameyGlyph";
-import { Button, buttonBase, buttonSizes, buttonVariants, cn, Popover } from "./ui";
+import { Button, Popover, cn } from "./ui";
 
-// "Edit with Framey": the preview server (`/api/open-in-desktop`) says whether to show it and whether the app can
-// take the project yet (its gate is the CLI's HANDOFF_READY); until then a press introduces Framey with the download.
+// "Install the desktop app": the preview server (`/api/open-in-desktop`) says whether to show it, whether the app is
+// here and whether it takes the project. With the app ready a press opens the project in it; otherwise the press
+// opens a card where Framey walks through download, install and open.
 const ROUTE = "/api/open-in-desktop";
 /** How far the pupils travel towards the pointer, in the glyph's own units. */
 const GAZE = 2.2;
 /** Long enough for the flight to finish before the label comes back. */
 const OPENING_MS = 1600;
+/** While the card is open and the app is not here yet, how often to ask the preview server again. */
+const POLL_MS = 2000;
+/** After this long without the app turning up, the card asks whether the download finished. */
+const SLOW_MS = 60_000;
 
 type OpenResult = { opened: true } | { opened: false; reason: string; downloadUrl: string };
 
-type DesktopRoute = { handoff: boolean; downloadUrl: string | null };
+type Eligibility = "open_in_app" | "download" | "no_app_for_platform";
 
-/** Null hides the button: no route (the app's own Studio), or nothing here to open or download. */
-function useDesktopRoute(): DesktopRoute | null {
+/** Every Guide step change, for the funnel: never a download counted as an install. */
+type GuideStep = "opened" | "closed" | "download_opened" | "install_detected";
+
+/** The download, tagged with this page's telemetry `tab_id` so a later install can be matched to the press. */
+const withCta = (url: string): string => {
+  const tagged = new URL(url);
+  tagged.searchParams.set("hf_cta", resolveTabId());
+  return tagged.toString();
+};
+
+const eligibilityOf = (route: DesktopRoute): Eligibility =>
+  route.handoff ? "open_in_app" : route.downloadUrl ? "download" : "no_app_for_platform";
+
+/** The preview server's answer, or null when there is none (the desktop's own Studio, or no server). */
+async function readRoute(): Promise<DesktopRoute | null> {
+  const res = await studioApiFetch(ROUTE);
+  if (!res.ok) return null;
+  const body = (await res.json()) as {
+    available?: unknown;
+    handoff?: unknown;
+    downloadUrl?: unknown;
+    os?: unknown;
+    installed?: unknown;
+  } | null;
+  if (!body) return null;
+  const downloadUrl = typeof body.downloadUrl === "string" ? body.downloadUrl : null;
+  return {
+    handoff: body.available === true && body.handoff === true,
+    downloadUrl: body.available === true ? downloadUrl : null,
+    context: {
+      os: typeof body.os === "string" ? body.os : "unknown",
+      app_installed: body.installed === true,
+      download_available: downloadUrl !== null,
+    },
+  };
+}
+
+/** Null hides the button: no route, or nothing here to open or download. `setRoute` takes a fresher answer. */
+function useDesktopRoute() {
   const [route, setRoute] = useState<DesktopRoute | null>(null);
   useEffect(() => {
     let live = true;
-    studioApiFetch(ROUTE)
-      .then((res) => (res.ok ? res.json() : null))
-      .then((body: { available?: unknown; handoff?: unknown; downloadUrl?: unknown } | null) => {
-        if (!live || body?.available !== true) return;
-        const handoff = body.handoff === true;
-        const downloadUrl = typeof body.downloadUrl === "string" ? body.downloadUrl : null;
-        if (handoff || downloadUrl) setRoute({ handoff, downloadUrl });
+    readRoute()
+      .then((answered) => {
+        if (!live || !answered) return;
+        trackStudioEvent("desktop_cta_eligibility", {
+          eligibility: eligibilityOf(answered),
+          ...answered.context,
+        });
+        if (answered.handoff || answered.downloadUrl) setRoute(answered);
       })
       .catch(() => {});
     return () => {
       live = false;
     };
   }, []);
-  return route;
+  return [route, setRoute] as const;
+}
+
+/** One impression per page, once the button is on screen. */
+function useImpression(anchor: React.RefObject<HTMLElement | null>, route: DesktopRoute | null) {
+  const shown = route !== null;
+  const routeRef = useRef(route);
+  routeRef.current = route;
+  useEffect(() => {
+    const el = anchor.current;
+    if (!shown || !el) return;
+    const record = () => {
+      const now = routeRef.current!;
+      trackStudioEvent("desktop_cta_impression", {
+        eligibility: eligibilityOf(now),
+        ...now.context,
+      });
+    };
+    if (typeof IntersectionObserver === "undefined") return record();
+    const seen = new IntersectionObserver((entries) => {
+      if (!entries.some((entry) => entry.isIntersecting)) return;
+      seen.disconnect();
+      record();
+    });
+    seen.observe(el);
+    return () => seen.disconnect();
+  }, [anchor, shown]);
 }
 
 /** Framey looks at the pointer: one listener, one write per frame, no re-render. */
@@ -64,97 +144,190 @@ function useGaze(
   }, [anchor, eye]);
 }
 
-export function OpenInDesktopButton() {
-  const { showToast } = useStudioShellContext();
-  const route = useDesktopRoute();
-  const [opening, setOpening] = useState(false);
-  // The card under the button, introducing Framey with the app's download.
-  const [downloadUrl, setDownloadUrl] = useState<string | null>(null);
-  const trigger = useRef<HTMLButtonElement>(null);
-  const eye = useRef<SVGGElement>(null);
-  useGaze(trigger, eye);
-  if (!route) return null;
+/** While the card is open and the app is not here, ask the preview server again; stops on close or once found. */
+function useInstallWatch(watching: boolean, onAnswer: (route: DesktopRoute) => void): void {
+  useEffect(() => {
+    if (!watching) return;
+    let live = true;
+    const ask = () =>
+      readRoute()
+        .then((answered) => live && answered && onAnswer(answered))
+        .catch(() => {});
+    void ask();
+    const timer = setInterval(ask, POLL_MS);
+    return () => {
+      live = false;
+      clearInterval(timer);
+    };
+  }, [watching, onAnswer]);
+}
 
-  const open = async () => {
-    if (!route.handoff) {
-      trackStudioEvent("toolbar_action", { action: "open_in_desktop" });
-      setDownloadUrl(route.downloadUrl);
+const LOOK =
+  "hf-framey-trigger gap-1.5 border border-accent/40 bg-accent/10 pl-1 font-semibold text-text-0 enabled:hover:bg-accent/20 hover:bg-accent/20";
+const LOOK_FAILED = "border-danger/45 bg-danger/8 text-danger-ink enabled:hover:bg-danger/14";
+
+/** The guide's state and the two actions that move it: the download and the hand-off. */
+function useGuide(route: DesktopRoute | null, setRoute: (route: DesktopRoute) => void) {
+  const { showToast } = useStudioShellContext();
+  const [cardOpen, setCardOpen] = useState(false);
+  const [opening, setOpening] = useState(false);
+  const [failed, setFailed] = useState(false);
+  const [downloaded, setDownloaded] = useState(false);
+  const [slow, setSlow] = useState(false);
+  const [arrived, setArrived] = useState(false);
+  const installed = route?.context.app_installed === true;
+  // The funnel counts one install per page, even if the app is removed and found again.
+  const installCounted = useRef(false);
+
+  const onAnswer = useCallback(
+    (answered: DesktopRoute) => {
+      if (!answered.context.app_installed) return;
+      setRoute(answered);
+      setArrived(true);
+      if (installCounted.current) return;
+      installCounted.current = true;
+      trackStudioEvent("desktop_cta_guide", { step: "install_detected", ...answered.context });
+    },
+    [setRoute],
+  );
+  useInstallWatch(cardOpen && route !== null && !installed, onAnswer);
+
+  useEffect(() => {
+    if (!downloaded || installed) return;
+    setSlow(false);
+    const timer = setTimeout(() => setSlow(true), SLOW_MS);
+    return () => clearTimeout(timer);
+  }, [downloaded, installed]);
+
+  if (!route) return null;
+  const context = route.context;
+  const guideStep = (step: GuideStep) =>
+    trackStudioEvent("desktop_cta_guide", { step, ...context });
+  const outcome = (result: "opened" | "sent_to_download" | "failed", reason?: string) =>
+    trackStudioEvent("desktop_cta_outcome", {
+      outcome: result,
+      ...(reason ? { reason } : {}),
+      ...context,
+    });
+
+  const showCard = (next: boolean) => {
+    if (next === cardOpen) return;
+    setCardOpen(next);
+    guideStep(next ? "opened" : "closed");
+  };
+
+  const download = () => {
+    if (!route.downloadUrl) return;
+    trackStudioEvent("toolbar_action", { action: "get_desktop_app", ...context });
+    const tab = window.open(withCta(route.downloadUrl), "_blank");
+    if (!tab) {
+      showToast(`Get the HyperFrames desktop app at ${route.downloadUrl}`, "info");
+      outcome("failed", "download_tab_blocked");
       return;
     }
+    tab.opener = null;
+    setDownloaded(true);
+    outcome("sent_to_download");
+    guideStep("download_opened");
+  };
+
+  const landed = async (result: OpenResult) => {
+    if (result.opened) {
+      outcome("opened");
+      showCard(false);
+      showToast("Opening this project in the HyperFrames desktop app", "info");
+      await new Promise((done) => setTimeout(done, OPENING_MS));
+      return;
+    }
+    outcome("failed", result.reason);
+    // The app is gone: back to the download. Anything else: say so where the person is, with a way through.
+    if (result.reason === "not-installed")
+      setRoute({ ...route, handoff: false, context: { ...context, app_installed: false } });
+    else setFailed(true);
+    showCard(true);
+  };
+
+  const open = async () => {
     if (opening) return;
     setOpening(true);
-    trackStudioEvent("toolbar_action", { action: "open_in_desktop" });
+    setFailed(false);
+    trackStudioEvent("toolbar_action", { action: "open_in_desktop", ...context });
     try {
-      const res = await studioApiFetch(ROUTE, { method: "POST" });
-      const result = (await res.json()) as OpenResult;
-      if (result.opened) {
-        showToast("Framey is opening this project in the HyperFrames desktop app", "info");
-        await new Promise((done) => setTimeout(done, OPENING_MS));
-      } else setDownloadUrl(result.downloadUrl);
+      const res = await studioApiFetch(ROUTE, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ cta: resolveTabId() }),
+      });
+      await landed((await res.json()) as OpenResult);
     } catch {
+      outcome("failed", "preview_server_unreachable");
       showToast("Couldn't reach the preview server to open the app", "error");
     } finally {
       setOpening(false);
     }
   };
 
+  const progress: Progress = { route, opening, failed, downloaded, slow, arrived };
+  return { progress, cardOpen, showCard, download, open };
+}
+
+export function OpenInDesktopButton() {
+  const projectDir = useFileManagerContextOptional()?.projectDir ?? null;
+  const [route, setRoute] = useDesktopRoute();
+  const trigger = useRef<HTMLButtonElement>(null);
+  const eye = useRef<SVGGElement>(null);
+  useGaze(trigger, eye);
+  useImpression(trigger, route);
+  const guide = useGuide(route, setRoute);
+  if (!guide) return null;
+  const { progress, cardOpen, showCard, download, open } = guide;
+  const label = labelOf(progress);
+  const waiting = isWaiting(progress);
+
   return (
     <Popover
-      open={downloadUrl !== null}
-      // The popover owns the trigger's press: a press runs the hand-off, and the card shows only when there is
-      // something to say (the download). A second handler on the button raced this one.
+      open={cardOpen}
+      // With the app ready the press is the hand-off itself; everything else opens the card.
       onOpenChange={(next) => {
-        if (next) void open();
-        else setDownloadUrl(null);
+        if (next && progress.route.handoff && !progress.failed) return void open();
+        showCard(next);
       }}
       side="bottom"
       align="end"
-      arrow
-      aria-label="Meet Framey"
-      className="w-72"
+      aria-label="Get the desktop app"
+      className="w-[360px] overflow-hidden p-0"
       trigger={
         <Button
           ref={trigger}
           variant="ghost"
           data-testid="header-open-in-desktop"
-          data-opening={opening || undefined}
-          title="Open this project in the HyperFrames desktop app and edit it with Framey"
-          className="hf-framey-trigger gap-1.5 border border-accent/40 bg-accent/10 pl-1 font-semibold text-text-0 enabled:hover:bg-accent/20"
-          icon={<FrameyGlyph size={24} className="hf-framey" eyeRef={eye} />}
+          data-opening={progress.opening || undefined}
+          aria-busy={progress.opening || waiting || undefined}
+          title={
+            progress.route.handoff
+              ? "Open this project in the HyperFrames desktop app"
+              : "Get the free HyperFrames desktop app"
+          }
+          className={cn(LOOK, progress.failed && LOOK_FAILED)}
+          icon={
+            <FrameyGlyph size={24} className="hf-framey" eyeRef={eye} mood={moodOf(progress)} />
+          }
         >
-          {opening ? "Opening in the app…" : "Edit with Framey"}
-          {!opening && (
-            <span className="rounded-full bg-accent px-1.5 text-[10px] leading-4 font-bold text-on-accent">
-              New
+          <Swap value={label}>{label}</Swap>
+          {waiting && (
+            <span className="rounded-full bg-on px-1.5 text-[10px] leading-4 font-bold text-accent-ink tabular-nums">
+              2 of 3
             </span>
           )}
         </Button>
       }
     >
-      <div className="flex items-center gap-2.5">
-        <FrameyGlyph size={36} />
-        <p className="text-step-12 font-medium text-text-0">Meet Framey</p>
-      </div>
-      <p className="mt-2 text-balance text-text-3">I live in the free HyperFrames desktop app:</p>
-      <ul className="mt-1.5 grid gap-1 text-text-1">
-        <li>Chat to change anything in the video</li>
-        <li>Draw on a frame to point at it</li>
-        <li>Watch me act out each edit</li>
-      </ul>
-      <div className="mt-3 flex items-center justify-end gap-2 whitespace-nowrap">
-        <Button variant="ghost" onClick={() => setDownloadUrl(null)}>
-          Not now
-        </Button>
-        <a
-          href={downloadUrl ?? undefined}
-          target="_blank"
-          rel="noopener noreferrer"
-          className={cn(buttonBase, buttonVariants.primary, buttonSizes.md)}
-          onClick={() => trackStudioEvent("toolbar_action", { action: "get_desktop_app" })}
-        >
-          Get the desktop app
-        </a>
-      </div>
+      <GuideCard
+        progress={progress}
+        projectDir={projectDir}
+        onDownload={download}
+        onOpen={() => void open()}
+      />
     </Popover>
   );
 }
diff --git a/packages/studio/src/styles/components.css b/packages/studio/src/styles/components.css
index 1ef5398b40..ae76e180bc 100644
--- a/packages/studio/src/styles/components.css
+++ b/packages/studio/src/styles/components.css
@@ -956,7 +956,7 @@
   }
 }
 
-/* Framey on the header's "Edit with Framey" (OpenInDesktopButton.tsx): a pulse as the page opens, a wiggle
+/* Framey on the header's "Install the desktop app" (OpenInDesktopButton.tsx): a pulse as the page opens, a wiggle
  * on hover, a flight towards the app while it opens. The eye follows the pointer from script. */
 @keyframes hf-framey-wiggle {
   0%,
@@ -1020,3 +1020,163 @@
     transition: none;
   }
 }
+
+/* Framey's moods, timed as the desktop app times them: it breathes and blinks, its eyes circle while it waits,
+ * it hops once when the app turns up, flies while a project hands over, and shakes when that fails. */
+.hf-framey-mood .hf-framey-body {
+  transform-box: fill-box;
+  transform-origin: 50% 60%;
+  animation: hf-framey-breath 3.27s ease-in-out infinite;
+}
+
+.hf-framey-mood .hf-framey-lid,
+.hf-framey-mood .hf-framey-whole {
+  transform-box: fill-box;
+  transform-origin: 50% 50%;
+}
+
+.hf-framey-mood .hf-framey-whole {
+  transform-origin: 50% 100%;
+}
+
+.hf-framey-mood:is([data-mood="idle"], [data-mood="found"]) .hf-framey-lid {
+  animation: hf-framey-blink 4.6s infinite;
+}
+
+.hf-framey-mood[data-mood="found"] .hf-framey-whole {
+  animation: hf-framey-hop 1.8s cubic-bezier(0.2, 0.8, 0.2, 1) 2;
+}
+
+.hf-framey-mood[data-mood="opening"] .hf-framey-whole {
+  animation: hf-framey-handoff 2.4s cubic-bezier(0.2, 0.8, 0.2, 1) infinite;
+}
+
+.hf-framey-mood[data-mood="error"] .hf-framey-whole {
+  animation: hf-framey-shake 0.6s ease-in-out 1;
+}
+
+.hf-framey-orbit {
+  animation: hf-framey-orbit 1.4s linear infinite;
+}
+
+@keyframes hf-framey-breath {
+  50% {
+    transform: scale(1.018);
+  }
+}
+
+@keyframes hf-framey-blink {
+  0%,
+  93%,
+  100% {
+    transform: scaleY(1);
+  }
+  95.5% {
+    transform: scaleY(0.12);
+  }
+}
+
+@keyframes hf-framey-hop {
+  0%,
+  40%,
+  100% {
+    transform: translateY(0);
+  }
+  20% {
+    transform: translateY(-7px);
+  }
+}
+
+@keyframes hf-framey-orbit {
+  0%,
+  100% {
+    transform: translate(3px, 0);
+  }
+  25% {
+    transform: translate(0, 3px);
+  }
+  50% {
+    transform: translate(-3px, 0);
+  }
+  75% {
+    transform: translate(0, -3px);
+  }
+}
+
+@keyframes hf-framey-handoff {
+  0% {
+    transform: none;
+  }
+  45%,
+  60% {
+    transform: translate(14px, -4px) rotate(10deg);
+    opacity: 1;
+  }
+  80% {
+    transform: translate(30px, -8px) rotate(12deg);
+    opacity: 0;
+  }
+  81% {
+    transform: translate(-10px, 0);
+    opacity: 0;
+  }
+  100% {
+    transform: none;
+    opacity: 1;
+  }
+}
+
+@keyframes hf-framey-shake {
+  0%,
+  100% {
+    transform: translateX(0);
+  }
+  20% {
+    transform: translateX(-3px);
+  }
+  40% {
+    transform: translateX(3px);
+  }
+  60% {
+    transform: translateX(-2px);
+  }
+  80% {
+    transform: translateX(2px);
+  }
+}
+
+/* The desktop-app guide card: a label or step that changes settles in; a finished step's tick pops in. */
+.hf-guide-swap {
+  animation: hf-guide-swap 180ms var(--ease-out-quint);
+}
+
+.hf-guide-tick {
+  animation: hf-guide-tick 300ms var(--ease-out-quint);
+}
+
+@keyframes hf-guide-swap {
+  from {
+    opacity: 0;
+    transform: translateY(3px);
+    filter: blur(2px);
+  }
+}
+
+@keyframes hf-guide-tick {
+  from {
+    opacity: 0;
+    transform: scale(0.3);
+    filter: blur(3px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hf-framey-mood .hf-framey-body,
+  .hf-framey-mood .hf-framey-lid,
+  .hf-framey-mood .hf-framey-whole,
+  .hf-framey-orbit,
+  .hf-guide-swap,
+  .hf-guide-tick {
+    animation: none;
+  }
+}
diff --git a/scripts/studio-runtime-smoke.mjs b/scripts/studio-runtime-smoke.mjs
index 379f93cd21..4d2843042a 100644
--- a/scripts/studio-runtime-smoke.mjs
+++ b/scripts/studio-runtime-smoke.mjs
@@ -52,7 +52,7 @@ const GET_RESPONSES = new Map([
   // interesting assertion is that the shell mounts clean, not that a blocking
   // notice renders. The notice has its own tests.
   ["/api/environment/ffmpeg", json({ ok: true })],
-  // The header's Edit with Framey asks this on load; shown, so the shell mounts with it.
+  // The header's "Install the desktop app" asks this on load; shown, so the shell mounts with it.
   [
     "/api/open-in-desktop",
     json({