@hienlh/ppm 0.22.1 → 0.22.3

package/src/web/components/explorer/search-panel.tsx

@@ -6,6 +6,7 @@ import { useTabStore } from "@/stores/tab-store";
 import { projectUrl, api } from "@/lib/api-client";
 import { cn } from "@/lib/utils";
 import { FileIcon } from "@/lib/file-icons";
+import { emitOnboardingEvidence } from "@/lib/onboarding/onboarding-types";
 
 interface SearchMatch {
   lineNum: number;
@@ -63,7 +64,7 @@ function OptionButton({ active, onClick, title, children }: { active: boolean; o
   );
 }
 
-export function SearchPanel() {
+export function SearchPanel({ onNavigate }: { onNavigate?: () => void } = {}) {
   const { activeProject } = useProjectStore(useShallow((s) => ({ activeProject: s.activeProject })));
   const openTab = useTabStore((s) => s.openTab);
 
@@ -82,8 +83,25 @@ export function SearchPanel() {
   const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
   const inputRef = useRef<HTMLInputElement>(null);
   const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const requestId = useRef(0);
+  const [searchError, setSearchError] = useState<string | null>(null);
+  const [searched, setSearched] = useState(false);
+  // Invalidate synchronously during render, including the debounce gap.
+  const signature = JSON.stringify([activeProject?.name, query, caseSensitive, wholeWord, useRegex, filesFilter]);
+  const currentSignature = useRef(signature);
+  if (currentSignature.current !== signature) {
+    currentSignature.current = signature;
+    requestId.current++;
+  }
 
   const doSearch = useCallback(async (q: string, cs: boolean, ww: boolean, rx: boolean, ff: string) => {
+    const id = ++requestId.current;
+    setSearchError(null);
+    setSearched(false);
+    setLoading(false);
+    setResults([]);
+    setTotal(0);
     setRegexError(false);
     if (!activeProject || (!rx && q.length < 2) || (rx && q.length < 1)) {
       setResults([]);
@@ -100,19 +118,30 @@ export function SearchPanel() {
       const data = await api.get<{ results: SearchResult[]; total: number }>(
         `${projectUrl(activeProject.name)}/files/search?${params}`
       );
+      if (id !== requestId.current) return;
       setResults(data.results);
       setTotal(data.total);
-    } catch {
+      setSearched(true);
+      const visible = !!panelRef.current?.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+      if (visible) emitOnboardingEvidence({ type: "search-succeeded", projectName: activeProject.name, requestId: String(id), visible });
+    } catch (error) {
+      if (id !== requestId.current) return;
       setResults([]);
+      setSearchError(error instanceof Error ? error.message : "Unable to search this project.");
     } finally {
-      setLoading(false);
+      if (id === requestId.current) setLoading(false);
     }
   }, [activeProject]);
 
   useEffect(() => {
     if (debounceRef.current) clearTimeout(debounceRef.current);
+    setSearched(false);
+    setSearchError(null);
+    setResults([]);
+    setTotal(0);
+    setLoading(false);
     debounceRef.current = setTimeout(() => doSearch(query, caseSensitive, wholeWord, useRegex, filesFilter), 300);
-    return () => { if (debounceRef.current) clearTimeout(debounceRef.current); };
+    return () => { requestId.current++; if (debounceRef.current) clearTimeout(debounceRef.current); };
   }, [query, caseSensitive, wholeWord, useRegex, filesFilter, doSearch]);
 
   useEffect(() => { inputRef.current?.focus(); }, []);
@@ -129,6 +158,7 @@ export function SearchPanel() {
       projectId: activeProject.name,
       closable: true,
     });
+    onNavigate?.();
   }
 
   function toggleCollapse(file: string) {
@@ -169,7 +199,7 @@ export function SearchPanel() {
   }
 
   return (
-    <div className="flex flex-col h-full">
+    <div ref={panelRef} data-onboarding="search" className="flex flex-col h-full">
       {/* Search input + options */}
       <div className="p-2 border-b border-border space-y-1.5">
         {/* Search row */}
@@ -265,7 +295,8 @@ export function SearchPanel() {
           {!loading && !replacing && replaceCount !== null && (
             <span className="text-success">{replaceCount} replacement{replaceCount !== 1 ? "s" : ""} made</span>
           )}
-          {!loading && !replacing && replaceCount === null && !regexError && query.length >= 2 && results.length === 0 && <span>No results</span>}
+          {searchError && <span role="alert" className="text-destructive">Search failed: {searchError} <button className="underline" onClick={() => void doSearch(query, caseSensitive, wholeWord, useRegex, filesFilter)}>Retry search</button></span>}
+          {!loading && !replacing && !searchError && searched && replaceCount === null && !regexError && results.length === 0 && <span>No results</span>}
           {!loading && !replacing && replaceCount === null && total > 0 && (
             <span>{total} result{total !== 1 ? "s" : ""} in {results.length} file{results.length !== 1 ? "s" : ""}</span>
           )}

package/src/web/components/git/git-status-panel.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useState, useCallback, useMemo } from "react";
+import { useEffect, useState, useCallback, useMemo, useRef } from "react";
+import { emitOnboardingEvidence } from "@/lib/onboarding/onboarding-types";
 import {
   Plus,
   Minus,
@@ -134,6 +135,29 @@ export function GitStatusPanel({ metadata, tabId, onNavigate }: GitStatusPanelPr
   // whose children are. This resolves which one every call below talks to.
   const gitRepo = useGitRepo(projectName);
   const gitRoot = gitRepo.repo?.path ?? activeProjectPath;
+  const panelRef = useRef<HTMLDivElement>(null);
+  const requestId = useRef(0);
+  const repoKey = `${projectName}:${gitRepo.repo?.path ?? ""}`;
+  const currentRepoKey = useRef(repoKey);
+  if (currentRepoKey.current !== repoKey) {
+    currentRepoKey.current = repoKey;
+    requestId.current++;
+  }
+  const [loadedRepoKey, setLoadedRepoKey] = useState<string | null>(null);
+  const activeProjectName = useProjectStore((s) => s.activeProject?.name);
+  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 || projectName !== activeProjectName || (tabId && tabId !== activeTabId) ||
+      !gitRepo.repo || loading || error || !status || loadedRepoKey !== repoKey) return;
+    const visible = !!panelRef.current?.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+    if (visible) emitOnboardingEvidence({ type: "git-ready", projectName, visible });
+  }, [onboardingRefresh, projectName, activeProjectName, tabId, activeTabId, gitRepo.repo, loading, error, status, loadedRepoKey, repoKey]);
   // Git Graph extension is available when it has registered its command.
   const gitGraphAvailable = useExtensionStore(
     (s) => s.contributions?.commands?.some((c) => c.command === "git-graph.view") ?? false,
@@ -143,12 +167,15 @@ export function GitStatusPanel({ metadata, tabId, onNavigate }: GitStatusPanelPr
     // No repository resolved yet: the panel is showing the picker, and asking
     // git in the container folder is what produced the error this replaced.
     if (!projectName || !gitRepo.repo) return;
+    const id = ++requestId.current;
     try {
       setLoading(true);
       const data = await api.get<GitStatus>(
         gitRepo.gitUrl("/status"),
       );
+      if (id !== requestId.current) return;
       setStatus(data);
+      setLoadedRepoKey(`${projectName}:${gitRepo.repo.path}`);
       setGitChangesCount(
         projectName,
         data.staged.length + data.unstaged.length + data.untracked.length,
@@ -156,9 +183,10 @@ export function GitStatusPanel({ metadata, tabId, onNavigate }: GitStatusPanelPr
       useGitStatusStore.getState().setMeta(projectName, data);
       setError(null);
     } catch (e) {
+      if (id !== requestId.current) return;
       setError(e instanceof Error ? e.message : "Failed to fetch status");
     } finally {
-      setLoading(false);
+      if (id === requestId.current) setLoading(false);
     }
   }, [projectName, gitRepo, setGitChangesCount]);
 
@@ -166,7 +194,7 @@ export function GitStatusPanel({ metadata, tabId, onNavigate }: GitStatusPanelPr
     fetchStatus();
     // Auto-reload every 5 seconds
     const interval = setInterval(fetchStatus, 5000);
-    return () => clearInterval(interval);
+    return () => { requestId.current++; clearInterval(interval); };
   }, [fetchStatus]);
 
   const stageFiles = async (files: string[]) => {
@@ -460,7 +488,7 @@ export function GitStatusPanel({ metadata, tabId, onNavigate }: GitStatusPanelPr
   );
 
   return (
-    <div className="flex flex-col h-full overflow-hidden">
+    <div ref={panelRef} data-onboarding="git" className="flex flex-col h-full overflow-hidden">
       <SidebarHeader icon={GitBranch} title={status?.current ? `On: ${status.current}` : "Source Control"}>
         <Button
           variant={viewMode === "flat" ? "secondary" : "ghost"}

package/src/web/components/layout/editor-panel.tsx

@@ -54,7 +54,7 @@ export function EditorPanel({ panelId, projectName }: EditorPanelProps) {
         panelCount > 1 && "border border-transparent",
         panelCount > 1 && isFocused && "border-primary/30",
       )}
-      onMouseDown={() => { if (usePanelStore.getState().focusedPanelId !== panelId) usePanelStore.getState().setFocusedPanel(panelId); }}
+      onMouseDown={() => { if (usePanelStore.getState().focusedPanelId !== panelId) usePanelStore.getState().setFocusedPanel(panelId, false); }}
     >
       <TabBar panelId={panelId} />
 

package/src/web/components/layout/mobile-drawer.tsx

@@ -5,6 +5,7 @@ import { useProjectStore } from "@/stores/project-store";
 import { useSettingsStore, type SidebarActiveTab } from "@/stores/settings-store";
 import { useExtensionStore } from "@/stores/extension-store";
 import { FileTree } from "@/components/explorer/file-tree";
+import { SearchPanel } from "@/components/explorer/search-panel";
 import { GitStatusPanel } from "@/components/git/git-status-panel";
 import { DatabaseSidebar } from "@/components/database/database-sidebar";
 import { JiraPanel } from "@/components/jira/jira-panel";
@@ -29,10 +30,10 @@ import { FeatureBadge } from "@/components/ui/feature-badge";
 import type { FeatureBadgeId } from "@/lib/feature-badges";
 import { cn } from "@/lib/utils";
 
-// Tab ids the mobile drawer can render content for. `search` is desktop-only for now;
+// Tab ids the mobile drawer can render content for;
 // ext views are supported via the `ext:` prefix.
 const MOBILE_SUPPORTED = new Set<string>([
-  "history", "teams", "explorer", "git", "database", "tunnels", "ai-resources", "jira",
+  "history", "teams", "explorer", "search", "git", "database", "tunnels", "ai-resources", "jira",
 ]);
 const isMobileSupported = (id: SidebarActiveTab) => MOBILE_SUPPORTED.has(id) || id.startsWith("ext:");
 
@@ -137,13 +138,14 @@ export function MobileDrawer({ isOpen, onClose, initialTab }: MobileDrawerProps)
         </div>
 
         {/* Tab content — scrollable */}
-        <div className="flex-1 overflow-y-auto min-h-0">
+        <div data-onboarding={isOpen ? activeTab : undefined} className="flex-1 overflow-y-auto min-h-0">
           {activeTab === "history" && (activeProject
             ? <SessionHistoryList variant="sidebar" projectName={activeProject.name} onNavigate={onClose} />
             : noProject)}
           {activeTab === "teams" && (activeProject ? <GroupList /> : noProject)}
           {activeTab === "explorer" && (activeProject ? <FileTree onFileOpen={onClose} /> : noProject)}
-          {activeTab === "git" && <GitStatusPanel metadata={{ projectName: activeProject?.name }} onNavigate={onClose} />}
+          {isOpen && activeTab === "search" && <SearchPanel onNavigate={onClose} />}
+          {isOpen && activeTab === "git" && <GitStatusPanel metadata={{ projectName: activeProject?.name }} onNavigate={onClose} />}
           {activeTab === "database" && <DatabaseSidebar />}
           {activeTab === "tunnels" && <TunnelManagerTab />}
           {activeTab === "jira" && <JiraPanel />}

package/src/web/components/layout/project-switcher.tsx

@@ -206,6 +206,7 @@ export const ProjectSwitcher = memo(function ProjectSwitcher() {
       <input ref={fileInputRef} type="file" accept="image/*" className="hidden" onChange={onFilePicked} />
       <button
         ref={btnRef}
+        data-onboarding="project"
         onClick={toggleFlyout}
         title="Switch project"
         className={cn(

package/src/web/components/layout/reparenting-tab.tsx

@@ -65,9 +65,11 @@ export function ReparentingTab({
       if (pid === DOCK_PANEL_ID || isWindowPanelId(pid)) return;
       usePanelStore.getState().setFocusedPanel(pid);
     };
-    wrapper.addEventListener("mousedown", onMouseDown, true);
+    wrapper.addEventListener("pointerdown", onMouseDown, true);
+    wrapper.addEventListener("focusin", onMouseDown, true);
     return () => {
-      wrapper.removeEventListener("mousedown", onMouseDown, true);
+      wrapper.removeEventListener("pointerdown", onMouseDown, true);
+      wrapper.removeEventListener("focusin", onMouseDown, true);
       wrapper.remove();
     };
   }, [wrapper, hiddenContainer]);

package/src/web/components/layout/sidebar.tsx

@@ -108,7 +108,7 @@ export const Sidebar = memo(function Sidebar() {
 
         <div className="flex-1 min-w-0 flex flex-col">
           {/* Panel content */}
-          <div className="flex-1 overflow-y-auto min-h-0">
+          <div className="flex-1 overflow-y-auto min-h-0" data-onboarding={sidebarActiveTab === "explorer" ? "explorer" : undefined}>
             {sidebarActiveTab === "explorer" && (
               activeProject ? (
                 <FileTree />

package/src/web/components/layout/tab-bar.tsx

@@ -448,6 +448,7 @@ export const TabBar = memo(function TabBar({ panelId }: TabBarProps) {
                   metadata: project ? { projectName: project.name } : undefined,
                 });
               } else {
+                usePanelStore.getState().setFocusedPanel(effectivePanelId, false);
                 openCommandPalette();
               }
             }}
@@ -503,4 +504,3 @@ export const TabBar = memo(function TabBar({ panelId }: TabBarProps) {
     </>
   );
 });
-

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

@@ -0,0 +1,15 @@
+import { Sparkles } from "@/lib/icons";
+import { Button } from "@/components/ui/button";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import { useProjectStore } from "@/stores/project-store";
+import { openQuickOrientation } from "./onboarding-quick-orientation";
+
+/** Reopening guidance never changes the workspace or the user's drafts. */
+export function OnboardingEntry({ compact = false }: { compact?: boolean }) {
+  const state = useOnboardingStore();
+  const projectName = useProjectStore((s) => s.activeProject?.name);
+  const canResume = state.goal && state.familiarity && state.status !== "finished";
+  return <div className={compact ? "flex flex-wrap items-center gap-2" : "grid gap-2"}><Button variant="outline" className={compact ? "min-h-11" : "min-h-11 w-full"}
+    onClick={() => canResume ? state.resume(projectName) : state.status === "finished" ? state.replay() : state.begin()}><Sparkles className="size-4" />{canResume ? "Resume guided tour" : state.status === "unseen" ? "Get started with PPM" : "Open guided tour"}</Button>
+    <Button variant="link" className="min-h-11" onClick={openQuickOrientation}>Quick orientation</Button></div>;
+}

package/src/web/components/onboarding/onboarding-file-help.tsx

@@ -0,0 +1,31 @@
+import { useEffect, useState } from "react";
+import { api, projectUrl } from "@/lib/api-client";
+import { Button } from "@/components/ui/button";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import type { FileDirEntry } from "../../../types/project";
+
+export function OnboardingFileHelp() {
+  const projectName = useOnboardingStore((state) => state.projectName);
+  const skip = useOnboardingStore((state) => state.skip);
+  const [empty, setEmpty] = useState(false);
+  useEffect(() => {
+    let cancelled = false;
+    let requestId = 0;
+    setEmpty(false);
+    if (!projectName) return;
+    const check = () => {
+      const id = ++requestId;
+      void api.get<FileDirEntry[]>(`${projectUrl(projectName)}/files/list`).then((entries) => {
+        if (!cancelled && id === requestId) setEmpty(entries.length === 0);
+      }).catch(() => { if (!cancelled && id === requestId) setEmpty(false); });
+    };
+    check();
+    window.addEventListener("ppm:onboarding-refresh", check);
+    return () => { cancelled = true; window.removeEventListener("ppm:onboarding-refresh", check); };
+  }, [projectName]);
+  return empty ? <div className="mt-3 rounded-lg border border-border p-3" role="status">
+    <p className="text-sm text-text-secondary">No files are visible in this project yet. You can create your own files later or choose another project. Nothing needs to be created for this tour.</p>
+    <Button variant="outline" className="w-full min-h-11 mt-2" onClick={skip}>Skip empty project step</Button>
+    <p className="text-xs text-text-secondary mt-2">This step will be marked skipped, not completed.</p>
+  </div> : <p className="text-xs text-text-secondary mt-2">Choose any text file, such as .txt, .js, .py or .md. No README or package.json is required. Markdown Preview counts too. If there is no readable file, use Skip step.</p>;
+}

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

@@ -0,0 +1,45 @@
+import { useState } from "react";
+import { Check, ChevronDown, ChevronUp, X } from "@/lib/icons";
+import { Button } from "@/components/ui/button";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import { getOnboardingCopy } from "@/lib/onboarding/onboarding-copy";
+import { getOnboardingSteps } from "@/lib/onboarding/onboarding-steps";
+import type { OnboardingStepId } from "@/lib/onboarding/onboarding-types";
+import { openQuickOrientation } from "./onboarding-quick-orientation";
+import { OnboardingFileHelp } from "./onboarding-file-help";
+
+export function OnboardingGuide({ collapsed, setCollapsed, onAction, onSettings }: {
+  collapsed: boolean; setCollapsed: (value: boolean) => void; onAction: (step: OnboardingStepId) => void; onSettings: () => void;
+}) {
+  const state = useOnboardingStore();
+  const [more, setMore] = useState(false);
+  const steps = getOnboardingSteps(state.goal);
+  const step = state.currentStep;
+  if (!step) return null;
+  const copy = getOnboardingCopy(step, state.familiarity ?? "beginner");
+  const index = steps.indexOf(step);
+  return <div className="p-4">
+    <div className="flex items-center gap-2">
+      <div className="flex-1 min-w-0"><p className="text-[11px] uppercase tracking-widest text-primary font-medium">Guided tour · {index + 1} of {steps.length}</p><h2 className="font-semibold text-sm mt-1" aria-live="polite">{copy.title}</h2></div>
+      <Button variant="ghost" className="min-h-11 min-w-11" aria-label={collapsed ? "Expand guide" : "Collapse guide"} onClick={() => setCollapsed(!collapsed)}>{collapsed ? <ChevronUp /> : <ChevronDown />}</Button>
+      <Button variant="ghost" className="min-h-11 min-w-11" aria-label="Pause tour" onClick={state.pause}><X /></Button>
+    </div>
+    {!collapsed && <>
+      <div className="flex gap-1 mt-3 mb-4" aria-label="Tour progress">{steps.map((id) => <span key={id} className={`h-1 flex-1 rounded-full ${state.completed.includes(id) ? "bg-primary" : state.skipped.includes(id) ? "bg-text-subtle" : "bg-border"}`} />)}</div>
+      <p className="text-sm text-text-secondary leading-relaxed">{copy.body}</p>
+      {step === "file" && <OnboardingFileHelp />}
+      {step === "run" && <p className="text-xs text-text-secondary mt-2">Open README directly, or package.json if no README is available. README Preview counts too.</p>}
+      {step === "run" && state.runDocumentReady && <p className="text-sm text-primary mt-2 flex items-center gap-1"><Check className="size-4" />Run instructions opened</p>}
+      <Button className="w-full mt-4 min-h-11" onClick={() => onAction(step)}>{step === "run" && state.runDocumentReady ? "I know where to run commands" : copy.action}</Button>
+      {(step === "chat" || step === "send") && <Button variant="ghost" className="w-full min-h-11 mt-1" onClick={onSettings}>AI settings</Button>}
+      <button className="text-xs text-primary py-3 min-h-11" onClick={() => setMore(!more)} aria-expanded={more}>{more ? "Less explanation" : "Explain this step"}</button>
+      {more && <p className="text-sm text-text-secondary leading-relaxed mb-3">{copy.more}</p>}
+      <Button variant="link" className="w-full min-h-11" onClick={openQuickOrientation}>Quick orientation</Button>
+      <div className="flex items-center justify-between border-t border-border pt-2">
+        <Button variant="ghost" className="min-h-11 px-2" disabled={index === 0} onClick={state.back}>Back</Button>
+        <Button variant="ghost" className="min-h-11 px-2" onClick={state.changeChoices}>Change guide</Button>
+        <Button variant="ghost" className="min-h-11 px-2" onClick={state.skip}>Skip step</Button>
+      </div>
+    </>}
+  </div>;
+}

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>;
+}