@hienlh/ppm 0.22.2 → 0.22.3

package/src/web/components/onboarding/onboarding-hint.tsx

@@ -0,0 +1,43 @@
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import { useVisualViewport } from "@/hooks/use-visual-viewport";
+
+export function findTourTarget(target: string): HTMLElement | undefined {
+  return Array.from(document.querySelectorAll<HTMLElement>(`[data-onboarding="${target}"]`))
+    .find((node) => node.getClientRects().length > 0 && node.getBoundingClientRect().width > 0);
+}
+
+/** Nonmodal: the real app stays interactive throughout a guided action. */
+export function OnboardingHint({ target, children, collapsed }: { target?: string; children: ReactNode; collapsed: boolean }) {
+  const mobile = useIsMobile();
+  const viewport = useVisualViewport(mobile);
+  const [rect, setRect] = useState<DOMRect | null>(null);
+  const card = useRef<HTMLElement>(null);
+  const [height, setHeight] = useState(360);
+  useEffect(() => {
+    if (!card.current) return;
+    const observer = new ResizeObserver(() => setHeight(card.current?.getBoundingClientRect().height ?? 360));
+    observer.observe(card.current);
+    return () => observer.disconnect();
+  }, []);
+  useEffect(() => {
+    if (!target || collapsed) { setRect(null); return; }
+    const measure = () => setRect(findTourTarget(target)?.getBoundingClientRect() ?? null);
+    measure();
+    const timer = window.setInterval(measure, 500);
+    window.addEventListener("resize", measure);
+    window.addEventListener("scroll", measure, true);
+    return () => { clearInterval(timer); window.removeEventListener("resize", measure); window.removeEventListener("scroll", measure, true); };
+  }, [target, collapsed]);
+  const left = !mobile && rect && rect.right + 380 < window.innerWidth ? rect.right + 12 : undefined;
+  const top = collapsed ? 48 : !mobile && rect
+    ? Math.max(16, Math.min(left !== undefined ? rect.top : rect.top - height - 12, window.innerHeight - height - 44)) : undefined;
+  return <>
+    {rect && !mobile && !collapsed && <div aria-hidden className="fixed pointer-events-none z-[59] rounded-md border-2 border-primary" style={{ left: rect.left, top: rect.top, width: rect.width, height: rect.height }} />}
+    <aside ref={card} aria-label="PPM guided tour" className="fixed z-[60] overflow-x-hidden rounded-xl border border-border bg-background text-foreground shadow-xl"
+      style={{ width: mobile ? "calc(100% - 24px)" : 352, maxWidth: "calc(100vw - 24px)", left: mobile ? 12 : left, right: mobile || left !== undefined ? undefined : 20,
+        top, bottom: top !== undefined ? undefined : mobile ? (viewport?.keyboardInset ?? 0) + 60 : 44, maxHeight: mobile ? "min(48dvh, 370px)" : "calc(100dvh - 80px)", overflowY: "auto" }}>
+      {children}
+    </aside>
+  </>;
+}

package/src/web/components/onboarding/onboarding-quick-orientation.tsx

@@ -0,0 +1,81 @@
+import { useRef, useState } from "react";
+import { Bell, Cloud, FolderTree, Settings, Bug, Search } from "@/lib/icons";
+import { Button } from "@/components/ui/button";
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from "@/components/ui/dialog";
+import { BUILTIN_SIDEBAR_TABS } from "@/lib/sidebar-tabs/tab-registry";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import { OnboardingStepTransition } from "./onboarding-step-transition";
+
+export const OPEN_QUICK_ORIENTATION = "ppm:open-quick-orientation";
+export function openQuickOrientation(): void {
+  window.dispatchEvent(new Event(OPEN_QUICK_ORIENTATION));
+}
+
+const descriptions: Record<string, string> = {
+  history: "Return to earlier AI conversations and continue where you left off.",
+  teams: "Find group conversations with multiple AI agents.",
+  explorer: "Browse files and folders in the selected project.",
+  search: "Find words across your project's files.",
+  git: "Review changed files and diffs before committing your work.",
+  database: "Browse connected databases and open the query editor.",
+  tunnels: "Manage tunnels for accessing local services remotely.",
+  "ai-resources": "Find available AI skills, commands and agents.",
+};
+const utilities = [
+  { title: "Notifications", icon: Bell, body: "See conversations that finished or need your attention." },
+  { title: "Cloud & Share", icon: Cloud, body: "Find sharing and remote-access options for this PPM instance." },
+  { title: "File Explorer", icon: FolderTree, body: "Browse the host computer, beyond the selected project." },
+  { title: "Settings", icon: Settings, body: "Configure AI, appearance and preferences; reopen guided tours." },
+  { title: "Report Bug", icon: Bug, body: "Open the bug-report form when something does not work." },
+];
+
+/** Optional reference: it never changes tour progress or executes a palette command. */
+export function OnboardingQuickOrientation({ onClose, onTryPalette }: { onClose: () => void; onTryPalette: () => void }) {
+  const [page, setPage] = useState<"palette" | "rail">("palette");
+  const mobile = useIsMobile();
+  const opener = useRef(document.activeElement as HTMLElement | null);
+  const openingPalette = useRef(false);
+  return <Dialog open onOpenChange={(open) => { if (!open) onClose(); }}>
+    <DialogContent className="max-h-[88dvh] overflow-y-auto sm:max-w-2xl p-5 sm:p-6" onCloseAutoFocus={(event) => {
+      event.preventDefault();
+      if (!openingPalette.current) {
+        const target = opener.current?.isConnected ? opener.current : document.querySelector<HTMLElement>('aside[aria-label="PPM guided tour"] button');
+        target?.focus();
+      }
+    }}>
+      <div className="text-xs font-medium uppercase tracking-widest text-primary">Quick orientation</div>
+      <DialogTitle className="text-xl">Find your way around PPM</DialogTitle>
+      <DialogDescription>Two shortcuts to getting comfortable. Your guided-tour progress stays saved.</DialogDescription>
+      <div className="flex gap-2" aria-label="Orientation topics">
+        <Button variant={page === "palette" ? "default" : "outline"} className="min-h-11 flex-1" aria-pressed={page === "palette"} onClick={() => setPage("palette")}>Command Palette</Button>
+        <Button variant={page === "rail" ? "default" : "outline"} className="min-h-11 flex-1" aria-pressed={page === "rail"} onClick={() => setPage("rail")}>{mobile ? "Navigation buttons" : "Left rail"}</Button>
+      </div>
+      <OnboardingStepTransition stepKey={page} order={page === "palette" ? 0 : 1}>
+      {page === "palette" ? <section className="space-y-4" aria-label="Command Palette introduction">
+        <div className="rounded-lg border border-border bg-surface p-4">
+          <Search className="size-6 text-primary mb-3" />
+          <h3 className="font-medium">One place to find actions and files</h3>
+          <p className="text-sm text-text-secondary mt-2">Type what you need, such as “Settings”, “Open Terminal”, or a filename. Choose a result to open it.</p>
+        </div>
+        <p className="text-sm text-text-secondary">{mobile ? "No keyboard required: tap Open Command Palette below. The same palette works on your phone." : "Double-tap Shift to open it from anywhere. F1 is the default shortcut and can be changed in Settings → Keyboard Shortcuts."}</p>
+        <p className="text-sm text-text-secondary">With a keyboard, use ↑ / ↓ to select a result, Enter to open it, and Escape to close. Opening the palette alone does not run a command.</p>
+        <Button className="w-full min-h-11" onClick={() => { openingPalette.current = true; onTryPalette(); }}>Open Command Palette</Button>
+      </section> : <section aria-label="Navigation introduction" className="space-y-4">
+        <p className="text-sm text-text-secondary">{mobile ? "Tap the menu button at the bottom to open navigation. These are the same sections shown in the left rail on desktop." : "The icon strip on the left switches between project sections. Hover for labels; click a section to open it. Clicking the active section again collapses it."}</p>
+        <div className="grid sm:grid-cols-2 gap-3">
+          {BUILTIN_SIDEBAR_TABS.map(({ id, label, icon: Icon }) => <div key={id} className="flex gap-3 rounded-lg border border-border p-3">
+            <Icon className="size-5 shrink-0 text-primary mt-0.5" /><div><h3 className="text-sm font-medium">{label}</h3><p className="text-sm text-text-secondary mt-1">{descriptions[id]}</p></div>
+          </div>)}
+        </div>
+        <h3 className="font-medium text-sm">{mobile ? "Utilities in the navigation menu" : "Utilities at the bottom of the rail"}</h3>
+        <div className="space-y-3">{utilities.filter((item) => !mobile || item.title !== "Notifications").map(({ title, icon: Icon, body }) => <div key={title} className="flex gap-3">
+          <Icon className="size-4 shrink-0 text-primary mt-1" /><p className="text-sm text-text-secondary"><strong className="font-medium text-foreground">{title}</strong> — {body}</p>
+        </div>)}</div>
+        {mobile && <p className="text-sm text-text-secondary">Mobile uses shorter labels: History, Tunnels and AI for the matching sections above; Files, Cloud and Bug for File Explorer, Cloud &amp; Share and Report Bug. The menu badge signals conversations needing attention.</p>}
+        <p className="text-xs text-text-secondary">Jira, Remote Desktop and extension buttons appear when available. Button order can be customized.</p>
+      </section>}
+      </OnboardingStepTransition>
+      <Button variant="ghost" className="min-h-11" onClick={onClose}>Back to what I was doing</Button>
+    </DialogContent>
+  </Dialog>;
+}

package/src/web/components/onboarding/onboarding-root.tsx

@@ -0,0 +1,137 @@
+import { useEffect, useState } from "react";
+import { Sparkles } from "@/lib/icons";
+import { Button } from "@/components/ui/button";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import { useProjectStore } from "@/stores/project-store";
+import { useTabStore } from "@/stores/tab-store";
+import { useSettingsStore, type SidebarActiveTab } from "@/stores/settings-store";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import { openSettings } from "@/components/settings/open-settings";
+import { ONBOARDING_EVENT, type OnboardingEvent, type OnboardingStepId } from "@/lib/onboarding/onboarding-types";
+import { ONBOARDING_TARGETS, getOnboardingSteps } from "@/lib/onboarding/onboarding-steps";
+import { OnboardingStepTransition } from "./onboarding-step-transition";
+import { ONBOARDING_SUGGESTED_PROMPT } from "@/lib/onboarding/onboarding-copy";
+import { OnboardingSetup } from "./onboarding-setup";
+import { OnboardingGuide } from "./onboarding-guide";
+import { findTourTarget, OnboardingHint } from "./onboarding-hint";
+import { useOnboardingSessionCheck } from "./use-onboarding-session-check";
+import { OPEN_QUICK_ORIENTATION, OnboardingQuickOrientation } from "./onboarding-quick-orientation";
+import { openCommandPalette } from "@/hooks/use-global-keybindings";
+import { openRunInstructions } from "@/lib/onboarding/run-instructions";
+
+export function OnboardingRoot({ openProjects, openNavigation, closeNavigation, paletteOpen = false, navigationOpen = false }: {
+  openProjects: () => void; openNavigation: (tab: SidebarActiveTab) => void; closeNavigation: () => void; paletteOpen?: boolean; navigationOpen?: boolean;
+}) {
+  const state = useOnboardingStore();
+  const project = useProjectStore((s) => s.activeProject);
+  const mobile = useIsMobile();
+  const [collapsed, setCollapsed] = useState(false);
+  const [notice, setNotice] = useState("");
+  const [orientationOpen, setOrientationOpen] = useState(false);
+  useEffect(() => {
+    const open = () => setOrientationOpen(true);
+    window.addEventListener(OPEN_QUICK_ORIENTATION, open);
+    return () => window.removeEventListener(OPEN_QUICK_ORIENTATION, open);
+  }, []);
+  useOnboardingSessionCheck(setNotice);
+  useEffect(() => {
+    const receive = (event: Event) => useOnboardingStore.getState().observe((event as CustomEvent<OnboardingEvent>).detail);
+    window.addEventListener(ONBOARDING_EVENT, receive);
+    return () => window.removeEventListener(ONBOARDING_EVENT, receive);
+  }, []);
+  useEffect(() => { state.setProjectContext(project?.name ?? null); }, [project?.name, state.setProjectContext]);
+  useEffect(() => {
+    if (state.status !== "active") return;
+    setNotice("");
+    setCollapsed(false);
+    const timer = window.setTimeout(() => window.dispatchEvent(new Event("ppm:onboarding-refresh")), 50);
+    return () => clearTimeout(timer);
+  }, [state.status, state.currentStep]);
+  useEffect(() => {
+    if (state.status !== "active" || orientationOpen || paletteOpen) return;
+    const escape = (event: KeyboardEvent) => { if (event.key === "Escape" && !event.defaultPrevented) useOnboardingStore.getState().pause(); };
+    window.addEventListener("keydown", escape);
+    return () => window.removeEventListener("keydown", escape);
+  }, [state.status, orientationOpen, paletteOpen]);
+
+  function navigate(tab: SidebarActiveTab) {
+    if (mobile) { openNavigation(tab); setCollapsed(true); }
+    else {
+      const settings = useSettingsStore.getState();
+      if (settings.sidebarCollapsed) settings.toggleSidebar();
+      settings.setSidebarActiveTab(tab);
+    }
+  }
+  function openWorkTab(type: "chat" | "terminal") {
+    if (!project) { state.setProjectContext(null); return; }
+    closeNavigation();
+    const tabs = useTabStore.getState();
+    const active = tabs.tabs.find((tab) => tab.id === tabs.activeTabId && tab.type === type && tab.projectId === project.name);
+    if (!active) tabs.openTab({ type, title: type === "chat" ? "New Chat" : `Terminal - ${project.name}`, projectId: project.name, metadata: { projectName: project.name }, closable: true });
+    window.setTimeout(() => window.dispatchEvent(new Event("ppm:onboarding-refresh")), 50);
+    if (mobile) setCollapsed(true);
+  }
+  function action(step: OnboardingStepId) {
+    if (step === "project") {
+      if (mobile) { openProjects(); setCollapsed(true); }
+      else {
+        const settings = useSettingsStore.getState();
+        if (settings.sidebarCollapsed) settings.toggleSidebar();
+        window.setTimeout(() => findTourTarget("project")?.click(), 0);
+      }
+    } else if (step === "run") {
+      if (!project) { setNotice("Choose a project first, or skip this step."); return; }
+      if (state.runDocumentReady) { state.observe({ type: "run-acknowledged", projectName: project.name, visible: true }); return; }
+      const projectName = project.name;
+      const stillCurrent = () => {
+        const current = useOnboardingStore.getState();
+        return current.status === "active" && current.currentStep === "run" && current.projectName === projectName && useProjectStore.getState().activeProject?.name === projectName;
+      };
+      setNotice("Looking for README or package.json…");
+      void openRunInstructions(projectName, stillCurrent).then((result) => {
+        if (!stillCurrent()) return;
+        if (result === "missing") setNotice("No README or package.json found in the project root. Browse Files to find other documentation, or skip this step.");
+        else if (result === "opened") { closeNavigation(); setCollapsed(true); setNotice(""); }
+      }).catch(() => { if (stillCurrent()) setNotice("Could not find run instructions. Click Find run instructions to retry, or skip this step."); });
+    } else if (step === "file") {
+      navigate("explorer");
+    } else if (step === "search" || step === "git") navigate(step);
+    else if (step === "chat" || step === "terminal") openWorkTab(step);
+    else if (step === "send" && project) {
+      window.dispatchEvent(new CustomEvent("ppm:onboarding-prompt", { detail: { projectName: project.name, text: ONBOARDING_SUGGESTED_PROMPT } }));
+      setNotice("Review the question in chat, then send it yourself. If you already have a draft, it stays unchanged.");
+      setCollapsed(true);
+    } else if (step === "history") {
+      const target = findTourTarget("chat-history");
+      if (target) { target.click(); setCollapsed(true); }
+      else setNotice("Open the chat you used, then choose its history menu. You can skip if no conversation was created.");
+    }
+  }
+  if (paletteOpen) return null;
+  // Keep every drawer row reachable, including the first file under the header.
+  // Closing the drawer restores the guide; completed tours still show their summary.
+  if (mobile && navigationOpen && collapsed && state.status === "active") return null;
+  if (orientationOpen) return <OnboardingQuickOrientation onClose={() => setOrientationOpen(false)} onTryPalette={() => {
+    setOrientationOpen(false);
+    setCollapsed(true);
+    requestAnimationFrame(() => openCommandPalette());
+  }} />;
+  if (state.status === "dismissed") return null;
+  if (state.status === "choosing") return <OnboardingSetup projectName={project?.name} />;
+  return <OnboardingHint collapsed={collapsed} target={state.status === "active" && state.currentStep ? ONBOARDING_TARGETS[state.currentStep] : undefined}>
+    <OnboardingStepTransition stepKey={state.status === "active" ? state.currentStep ?? "project" : state.status}
+      order={state.status === "finished" ? 100 : state.status === "active" ? getOnboardingSteps(state.goal).indexOf(state.currentStep!) + 1 : 0}>
+    {state.status === "active" ? <>
+      <OnboardingGuide collapsed={collapsed} setCollapsed={setCollapsed} onAction={action} onSettings={() => { openSettings("ai-provider"); setCollapsed(true); }} />
+      {notice && !collapsed && <p role="status" className="px-4 pb-4 text-xs text-text-secondary">{notice}</p>}
+    </> : <div className="p-5">
+      <div className="flex items-center gap-2 text-primary text-xs uppercase tracking-widest"><Sparkles className="size-4" />Your first steps</div>
+      <h2 className="font-semibold text-lg mt-2">{state.status === "finished" ? "Your walkthrough is complete" : state.status === "paused" ? "Continue when you're ready" : "Get started with PPM"}</h2>
+      <p className="text-sm text-text-secondary leading-relaxed mt-2">{state.status === "finished" ? `${state.completed.length} steps completed${state.skipped.length ? ` · ${state.skipped.length} skipped` : ""}. Choose another path, or keep exploring.` : state.status === "paused" ? "Your progress is saved in this browser. Resume here or choose a different guide." : "Choose a guide that fits your experience, then try your first task."}</p>
+      <Button className="w-full min-h-11 mt-4" onClick={() => { setCollapsed(false); state.status === "paused" ? state.resume(project?.name ?? null) : state.status === "finished" ? state.replay() : state.begin(); }}>{state.status === "paused" ? "Resume tour" : state.status === "finished" ? "Try another guide" : "Start guided tour"}</Button>
+      <Button variant="ghost" className="w-full min-h-11 mt-1" onClick={state.dismiss}>{state.status === "finished" ? "Keep exploring" : "Maybe later"}</Button>
+      <Button variant="link" className="w-full min-h-11" onClick={() => setOrientationOpen(true)}>Quick orientation</Button>
+    </div>}
+    </OnboardingStepTransition>
+  </OnboardingHint>;
+}

package/src/web/components/onboarding/onboarding-run-document-preview.tsx

@@ -0,0 +1,23 @@
+import { useEffect, useRef, type ReactNode } from "react";
+import { useTabStore } from "@/stores/tab-store";
+import { emitOnboardingEvidence } from "@/lib/onboarding/onboarding-types";
+
+/** Loaded Markdown is readable in Preview too; a Suspense fallback never counts. */
+export function OnboardingRunDocumentPreview({ projectName, filePath, tabId, ready, children }: {
+  projectName?: string; filePath?: string; tabId?: string; ready: boolean; children: ReactNode;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const activeTabId = useTabStore((state) => state.activeTabId);
+  useEffect(() => {
+    const report = () => {
+      if (!ready || !projectName || !filePath || !tabId || activeTabId !== tabId) return;
+      const visible = !!ref.current?.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+      if (visible) emitOnboardingEvidence({ type: "file-ready", projectName, tabId, visible,
+        isRunDocument: /^readme(?:\.[^/\\]+)?$/i.test(filePath.split(/[/\\]/).pop() ?? "") });
+    };
+    report();
+    window.addEventListener("ppm:onboarding-refresh", report);
+    return () => window.removeEventListener("ppm:onboarding-refresh", report);
+  }, [projectName, filePath, tabId, ready, activeTabId]);
+  return <div ref={ref} className="flex flex-1 min-h-0 flex-col">{children}</div>;
+}

package/src/web/components/onboarding/onboarding-setup.tsx

@@ -0,0 +1,50 @@
+import { useRef, useState } from "react";
+import { Sparkles, Code, MessageSquare, ArrowLeft } from "@/lib/icons";
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import type { OnboardingFamiliarity, OnboardingGoal } from "@/lib/onboarding/onboarding-types";
+import { OnboardingStepTransition } from "./onboarding-step-transition";
+
+const levels: Array<{ id: OnboardingFamiliarity; title: string; body: string; icon: typeof Sparkles }> = [
+  { id: "beginner", title: "I'm just getting started", body: "One step at a time, with the basics explained.", icon: Sparkles },
+  { id: "familiar", title: "I've used similar tools", body: "A quick introduction to finding your way around PPM.", icon: Sparkles },
+  { id: "advanced", title: "I'm a developer / advanced user", body: "Go straight to the workspace and tools.", icon: Code },
+];
+const goals: Array<{ id: OnboardingGoal; title: string; body: string; icon: typeof Sparkles }> = [
+  { id: "ai", title: "Work with AI", body: "Ask about a project and find your conversation again.", icon: MessageSquare },
+  { id: "explore", title: "Explore a project", body: "Open a file and search through your project.", icon: Sparkles },
+  { id: "developer", title: "Use development tools", body: "Find the terminal, Git changes and run instructions.", icon: Code },
+];
+
+export function OnboardingSetup({ projectName }: { projectName?: string }) {
+  const store = useOnboardingStore();
+  const opener = useRef(document.activeElement as HTMLElement | null);
+  const [screen, setScreen] = useState<"level" | "goal">("level");
+  return <Dialog open onOpenChange={(open) => { if (!open) store.dismiss(); }}>
+    <DialogContent onCloseAutoFocus={(event) => {
+      event.preventDefault();
+      const target = opener.current?.isConnected ? opener.current : document.querySelector<HTMLElement>('aside[aria-label="PPM guided tour"] button');
+      target?.focus();
+    }} className="max-h-[90dvh] overflow-y-auto sm:max-w-[520px] p-5 sm:p-7">
+      <OnboardingStepTransition stepKey={screen} order={screen === "level" ? 0 : 1} className="grid gap-4">
+      <div className="text-xs font-medium tracking-widest uppercase text-primary">Your first steps · {screen === "level" ? "1" : "2"} of 2</div>
+      <DialogTitle className="text-2xl leading-tight">{screen === "level" ? "Make PPM feel familiar" : "What would you like to do first?"}</DialogTitle>
+      <DialogDescription>{screen === "level" ? "Choose the amount of guidance that suits you. You can change this anytime." : "Every path is available to you. Start with something useful."}</DialogDescription>
+      <div className="grid gap-3 mt-1">
+        {screen === "level" ? levels.map(({ id, title, body, icon: Icon }) =>
+          <button key={id} onClick={() => { store.chooseFamiliarity(id); setScreen("goal"); }} className="flex items-start gap-4 rounded-lg border border-border bg-surface p-4 text-left hover:border-primary focus-visible:outline-2 focus-visible:outline-primary">
+            <Icon className="size-5 shrink-0 text-primary mt-0.5" /><span><span className="block font-medium text-sm">{title}</span><span className="block mt-1 text-sm text-text-secondary">{body}</span></span>
+          </button>) : goals.map(({ id, title, body, icon: Icon }) =>
+          <button key={id} onClick={() => { store.chooseGoal(id); store.start(projectName); }} className="flex items-start gap-4 rounded-lg border border-border bg-surface p-4 text-left hover:border-primary focus-visible:outline-2 focus-visible:outline-primary">
+            <Icon className="size-5 shrink-0 text-primary mt-0.5" /><span><span className="block font-medium text-sm">{title}{id === "ai" && <span className="ml-2 text-xs text-primary">Suggested</span>}</span><span className="block mt-1 text-sm text-text-secondary">{body}</span></span>
+          </button>)}
+      </div>
+      <div className="flex items-center justify-between">
+        {screen === "goal" ? <Button variant="ghost" className="min-h-11" onClick={() => setScreen("level")}><ArrowLeft />Back</Button> : <span />}
+        <Button variant="ghost" className="min-h-11 text-text-secondary" onClick={store.dismiss}>I'll explore on my own</Button>
+      </div>
+      </OnboardingStepTransition>
+    </DialogContent>
+  </Dialog>;
+}

package/src/web/components/onboarding/onboarding-step-transition.tsx

@@ -0,0 +1,27 @@
+import { useLayoutEffect, useRef, type ReactNode } from "react";
+
+/** Animate the existing content node: no delayed state updates or duplicate controls. */
+export function OnboardingStepTransition({ stepKey, order, className, children }: {
+  stepKey: string; order: number; className?: string; children: ReactNode;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const previous = useRef({ stepKey, order });
+  useLayoutEffect(() => {
+    const before = previous.current;
+    previous.current = { stepKey, order };
+    const node = ref.current;
+    if (before.stepKey === stepKey || !node?.animate) return;
+    const preference = window.matchMedia("(prefers-reduced-motion: reduce)");
+    if (preference.matches) return;
+    const animation = node.animate([
+      { opacity: 0.35, transform: `translateX(${order < before.order ? -12 : 12}px)` },
+      { opacity: 1, transform: "translateX(0)" },
+    ], { duration: 200, easing: "cubic-bezier(0.2, 0, 0, 1)" });
+    // Canceling on rapid navigation/unmount rejects finished; that is expected.
+    void animation.finished.catch(() => {});
+    const stop = () => { if (preference.matches) animation.cancel(); };
+    preference.addEventListener("change", stop);
+    return () => { animation.cancel(); preference.removeEventListener("change", stop); };
+  }, [stepKey, order]);
+  return <div ref={ref} data-onboarding-transition={stepKey} className={className}>{children}</div>;
+}

package/src/web/components/onboarding/use-onboarding-session-check.ts

@@ -0,0 +1,32 @@
+import { useEffect } from "react";
+import { api, projectUrl } from "@/lib/api-client";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import type { SessionListResponse } from "../../../types/chat";
+
+/** Revalidate a restored history target without opening or sending any chat. */
+export function useOnboardingSessionCheck(setNotice: (message: string) => void): void {
+  const { status, currentStep, projectName, sessionId } = useOnboardingStore();
+  useEffect(() => {
+    if (status !== "active" || currentStep !== "history" || !projectName || !sessionId) return;
+    let cancelled = false;
+    const check = async () => {
+      let offset = 0;
+      for (let page = 0; page < 10; page++) {
+        const result = await api.get<SessionListResponse>(`${projectUrl(projectName)}/chat/sessions?limit=100&offset=${offset}`);
+        if (cancelled || result.sessions.some((session) => session.id === sessionId)) return;
+        if (!result.hasMore) {
+          useOnboardingStore.setState((state) => state.status === "active" && state.sessionId === sessionId && state.currentStep === "history" ? {
+            currentStep: "chat", sessionId: null, attempt: null,
+            completed: state.completed.filter((id) => id === "project"), skipped: [],
+          } : {});
+          setNotice("That conversation is no longer available. Open a chat to try again, or skip this step.");
+          return;
+        }
+        offset += result.sessions.filter((session) => !session.pinned).length;
+      }
+      if (!cancelled) setNotice("Open chat history to find the conversation, or skip this step.");
+    };
+    void check().catch(() => { if (!cancelled) setNotice("History could not be checked. Try the history menu again when connected, or pause the tour."); });
+    return () => { cancelled = true; };
+  }, [status, currentStep, projectName, sessionId, setNotice]);
+}

package/src/web/components/settings/general-settings-section.tsx

@@ -16,6 +16,7 @@ import { Switch } from "@/components/ui/switch";
 import { useSettingsStore } from "@/stores/settings-store";
 import { wakeLockSupport } from "@/hooks/use-wake-lock";
 import { ChangePasswordSection } from "./change-password-section";
+import { OnboardingEntry } from "@/components/onboarding/onboarding-entry";
 
 export function GeneralSettingsSection() {
   const { deviceName, setDeviceName, version, keepScreenAwake, setKeepScreenAwake } = useSettingsStore(
@@ -51,6 +52,12 @@ export function GeneralSettingsSection() {
 
   return (
     <div className="space-y-6">
+      <section className="space-y-2">
+        <h3 className="text-sm font-medium">Learn PPM</h3>
+        <p className="text-sm text-muted-foreground">Choose your experience and a task. Guidance is saved in this browser.</p>
+        <OnboardingEntry compact />
+      </section>
+      <Separator />
       <section className="space-y-2">
         <Label htmlFor="device-name">Device Name</Label>
         <div className="flex gap-2">

package/src/web/components/terminal/terminal-tab.tsx

@@ -8,6 +8,8 @@ import { copyToClipboard } from "@/lib/clipboard";
 import { RotateCcw, MessageSquare } from "@/lib/icons";
 import "@xterm/xterm/css/xterm.css";
 import { toast } from "sonner";
+import { useTabStore } from "@/stores/tab-store";
+import { emitOnboardingEvidence } from "@/lib/onboarding/onboarding-types";
 
 import { TerminalMobileToolbar } from "./terminal-mobile-toolbar";
 import { TerminalLinksSheet } from "./terminal-links-sheet";
@@ -27,6 +29,18 @@ export const TerminalTab = memo(function TerminalTab({ metadata, tabId }: Termin
   const [ctrlMode, setCtrlMode] = useState(false);
   const [selectMode, setSelectMode] = useState(false);
   const [linksOpen, setLinksOpen] = useState(false);
+  const activeTabId = useTabStore((s) => s.activeTabId);
+  const [onboardingRefresh, setOnboardingRefresh] = useState(0);
+  useEffect(() => {
+    const refresh = () => setOnboardingRefresh((n) => n + 1);
+    window.addEventListener("ppm:onboarding-refresh", refresh);
+    return () => window.removeEventListener("ppm:onboarding-refresh", refresh);
+  }, []);
+  useEffect(() => {
+    if (!projectName || !tabId || activeTabId !== tabId || !connected || !shellReady || reconnecting || exited) return;
+    const visible = !!containerRef.current?.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+    if (visible) emitOnboardingEvidence({ type: "terminal-ready", projectName, tabId, visible });
+  }, [onboardingRefresh, projectName, tabId, activeTabId, connected, shellReady, reconnecting, exited]);
 
   useTerminalTouchSelection(containerRef, selectMode);
 
@@ -125,7 +139,7 @@ export const TerminalTab = memo(function TerminalTab({ metadata, tabId }: Termin
   const isMobile = typeof window !== "undefined" && "ontouchstart" in window;
 
   return (
-    <div className="flex flex-col h-full min-h-0">
+    <div data-onboarding="terminal" className="flex flex-col h-full min-h-0">
       {/* Status bar */}
       <div className="flex items-center gap-2 px-3 py-1 bg-surface border-b border-border text-xs">
         <span

package/src/web/hooks/use-chat.ts

@@ -1,4 +1,5 @@
 import { useState, useCallback, useRef, useEffect, useMemo, startTransition } from "react";
+import { ChatAttemptLifecycle, type ChatAttemptEvent } from "@/lib/chat-attempt-lifecycle";
 import { useWebSocket } from "./use-websocket";
 import { api, projectUrl } from "@/lib/api-client";
 import { flattenWithExpansions, prefixPreCompactIds } from "@/lib/flatten-expansions";
@@ -130,7 +131,12 @@ export function useChat(
    * empty even though the conversation is on disk under the new id.
    */
   onSessionMigrated?: (newSessionId: string) => void,
+  onAttempt?: (event: ChatAttemptEvent) => void,
 ): UseChatReturn {
+  const attemptObserverRef = useRef(onAttempt);
+  attemptObserverRef.current = onAttempt;
+  const attemptRef = useRef<ChatAttemptLifecycle | null>(null);
+  if (!attemptRef.current) attemptRef.current = new ChatAttemptLifecycle((event) => attemptObserverRef.current?.(event));
   const [messages, setMessages] = useState<ChatMessage[]>([]);
   /** Map of compactMessageId → pre-compact messages (already ID-prefixed). Ephemeral. */
   const [expansions, setExpansions] = useState<Map<string, ChatMessage[]>>(new Map());
@@ -609,6 +615,7 @@ export function useChat(
       }
 
       case "error": {
+        if (!isReplayingRef.current) attemptRef.current?.fail();
         setMessages((prev) => {
           const last = prev[prev.length - 1];
           if (last?.role === "assistant") {
@@ -703,6 +710,7 @@ export function useChat(
       }
 
       case "done": {
+        if (!isReplayingRef.current) attemptRef.current?.finish(!!streamingContentRef.current.trim());
         // Idempotent: may receive duplicate done (provider + stream loop finally)
         if (phaseRef.current === "idle") break;
         if (ev.contextWindowPct != null) {
@@ -815,6 +823,7 @@ export function useChat(
     if ((data as any).type === "session_migrated") {
       const migratedTo = (data as any).newSessionId as string | undefined;
       if (migratedTo && migratedTo !== sessionIdRef.current) {
+        attemptRef.current?.migrate(migratedTo);
         onSessionMigratedRef.current?.(migratedTo);
       }
       return;
@@ -1015,6 +1024,7 @@ export function useChat(
     idleTimeoutMs: 45_000, // Server sends a heartbeat every 15 seconds.
     onConnectionChange: (connected) => {
       if (!connected) {
+        attemptRef.current?.fail();
         setIsConnected(false);
         setIsReconnecting(true);
       }
@@ -1028,6 +1038,7 @@ export function useChat(
   // Load history and reset state when session changes
   useEffect(() => {
     let cancelled = false;
+    attemptRef.current?.select(sessionId);
     const historyReconciled = historyReconciledRef.current;
     turnFinalizedRef.current = false;
     historyActivityRef.current++;
@@ -1170,6 +1181,7 @@ export function useChat(
       historyActivityRef.current++;
 
       const isFollowUp = phaseRef.current !== "idle";
+      if (sessionIdRef.current) attemptRef.current?.start(sessionIdRef.current, !isFollowUp, isConnected && connectedSessionId === sessionIdRef.current);
       turnFinalizedRef.current = false;
 
       if (isFollowUp) {
@@ -1227,7 +1239,7 @@ export function useChat(
         ...(thinkingRef.current !== null && { thinking: thinkingRef.current }),
       }));
     },
-    [send],
+    [send, isConnected, connectedSessionId],
   );
 
   const setModel = useCallback(
@@ -1294,6 +1306,7 @@ export function useChat(
   );
 
   const cancelStreaming = useCallback(() => {
+    attemptRef.current?.fail();
     if (phaseRef.current === "idle") return;
     send(JSON.stringify({ type: "cancel" }));
     const finalContent = streamingContentRef.current;

package/src/web/hooks/use-session-history.ts

@@ -2,7 +2,7 @@ import { useState, useEffect, useCallback, useRef } from "react";
 import { api, projectUrl } from "@/lib/api-client";
 import { useTabStore } from "@/stores/tab-store";
 import { useDebouncedValue } from "@/hooks/use-debounced-value";
-import type { SessionInfo, SessionListResponse, ProjectTag } from "../../types/chat";
+import { compareSessionsByActivity, type SessionInfo, type SessionListResponse, type ProjectTag } from "../../types/chat";
 
 const PAGE_SIZE = 50;
 
@@ -145,11 +145,7 @@ export function useSessionHistory({
       }
       setSessions((prev) => {
         const updated = prev.map((s) => s.id === session.id ? { ...s, pinned: !s.pinned } : s);
-        return updated.sort((a, b) => {
-          if (a.pinned && !b.pinned) return -1;
-          if (!a.pinned && b.pinned) return 1;
-          return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
-        });
+        return updated.sort(compareSessionsByActivity);
       });
     } catch { /* silent */ }
   }, [projectName]);

package/src/web/lib/chat-attempt-lifecycle.ts

@@ -0,0 +1,46 @@
+/** Local dispatch evidence, deliberately independent of tour state and server turn IDs. */
+export interface ChatAttemptEvent {
+  type: "started" | "succeeded" | "failed" | "session";
+  attemptId: string;
+  sessionId: string;
+  previousSessionId?: string;
+  hasContent?: boolean;
+}
+
+export class ChatAttemptLifecycle {
+  private attempt: { attemptId: string; sessionId: string } | null = null;
+  constructor(private emit: (event: ChatAttemptEvent) => void) {}
+
+  start(sessionId: string, idle: boolean, connected: boolean) {
+    // A follow-up can overlap an earlier done frame: never attribute it as success.
+    this.fail();
+    if (!idle || !connected) return;
+    this.attempt = { sessionId, attemptId: crypto.randomUUID() };
+    this.emit({ type: "started", ...this.attempt });
+  }
+
+  migrate(sessionId: string) {
+    if (!this.attempt || this.attempt.sessionId === sessionId) return;
+    const previousSessionId = this.attempt.sessionId;
+    this.attempt.sessionId = sessionId;
+    this.emit({ type: "session", ...this.attempt, previousSessionId });
+  }
+
+  select(sessionId: string | null) {
+    if (this.attempt && this.attempt.sessionId !== sessionId) this.fail();
+  }
+
+  fail() {
+    if (!this.attempt) return;
+    const attempt = this.attempt;
+    this.attempt = null;
+    this.emit({ type: "failed", ...attempt });
+  }
+
+  finish(hasContent: boolean) {
+    if (!this.attempt) return;
+    const attempt = this.attempt;
+    this.attempt = null;
+    this.emit({ type: hasContent ? "succeeded" : "failed", ...attempt, hasContent });
+  }
+}