@geminilight/mindos 0.5.28 → 0.5.29

package/app/app/api/update/route.ts

@@ -0,0 +1,41 @@
+export const dynamic = 'force-dynamic';
+import { NextResponse } from 'next/server';
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+
+/**
+ * POST /api/update — trigger `mindos update` as a detached child process.
+ *
+ * Similar to /api/restart: spawns the CLI command and returns immediately.
+ * The update process will npm install, remove build stamp, and restart
+ * the server. The current process will be killed during restart.
+ */
+export async function POST() {
+  try {
+    const cliPath = process.env.MINDOS_CLI_PATH || resolve(process.cwd(), '..', 'bin', 'cli.js');
+    const nodeBin = process.env.MINDOS_NODE_BIN || process.execPath;
+
+    // Strip MINDOS_* env vars so the child reads fresh config
+    const childEnv = { ...process.env };
+    delete childEnv.MINDOS_WEB_PORT;
+    delete childEnv.MINDOS_MCP_PORT;
+    delete childEnv.MIND_ROOT;
+    delete childEnv.AUTH_TOKEN;
+    delete childEnv.WEB_PASSWORD;
+
+    const child = spawn(nodeBin, [cliPath, 'update'], {
+      detached: true,
+      stdio: 'ignore',
+      env: childEnv,
+    });
+    child.unref();
+
+    // Unlike /api/restart, we do NOT process.exit() here.
+    // `mindos update` will npm install first (30s+), then restart which
+    // kills this process. Exiting early would break the response.
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/app/app/explore/page.tsx

@@ -0,0 +1,12 @@
+import { redirect } from 'next/navigation';
+import { readSettings } from '@/lib/settings';
+import ExploreContent from '@/components/explore/ExploreContent';
+
+export const dynamic = 'force-dynamic';
+
+export default function ExplorePage() {
+  const settings = readSettings();
+  if (settings.setupPending) redirect('/setup');
+
+  return <ExploreContent />;
+}

package/app/components/ActivityBar.tsx

@@ -3,6 +3,7 @@
 import { useRef, useCallback } from 'react';
 import Link from 'next/link';
 import { FolderTree, Search, Settings, RefreshCw, Blocks, Bot, ChevronLeft, ChevronRight } from 'lucide-react';
+import { useLocale } from '@/lib/LocaleContext';
 import { DOT_COLORS, getStatusLevel } from './SyncStatusBar';
 import type { SyncStatus } from './settings/SyncTab';
 import Logo from './Logo';
@@ -32,9 +33,11 @@ interface RailButtonProps {
   buttonRef?: React.Ref<HTMLButtonElement>;
   /** Optional overlay badge (e.g. status dot) rendered inside the button */
   badge?: React.ReactNode;
+  /** Optional data-walkthrough attribute for interactive walkthrough targeting */
+  walkthroughId?: string;
 }
 
-function RailButton({ icon, label, shortcut, active = false, expanded, onClick, buttonRef, badge }: RailButtonProps) {
+function RailButton({ icon, label, shortcut, active = false, expanded, onClick, buttonRef, badge, walkthroughId }: RailButtonProps) {
   return (
     <button
       ref={buttonRef}
@@ -42,6 +45,7 @@ function RailButton({ icon, label, shortcut, active = false, expanded, onClick,
       aria-pressed={active}
       aria-label={label}
       title={expanded ? undefined : (shortcut ? `${label} (${shortcut})` : label)}
+      data-walkthrough={walkthroughId}
       className={`
         relative flex items-center ${expanded ? 'justify-start px-3 w-full' : 'justify-center w-10'} h-10 rounded-md transition-colors
         ${active
@@ -79,6 +83,7 @@ export default function ActivityBar({
 }: ActivityBarProps) {
   const lastClickRef = useRef(0);
   const syncBtnRef = useRef<HTMLButtonElement>(null);
+  const { t } = useLocale();
 
   /** Debounce rapid clicks (300ms) — shared across all Rail buttons */
   const debounced = useCallback((fn: () => void) => {
@@ -109,6 +114,7 @@ export default function ActivityBar({
       role="toolbar"
       aria-label="Navigation"
       aria-orientation="vertical"
+      data-walkthrough="activity-bar"
     >
       {/* Content wrapper — overflow-hidden prevents text flash during width transitions */}
       <div className="flex flex-col h-full w-full overflow-hidden">
@@ -126,10 +132,10 @@ export default function ActivityBar({
 
         {/* ── Middle: Core panel toggles ── */}
         <div className={`flex flex-col ${expanded ? 'px-1.5' : 'items-center'} gap-1 py-2`}>
-          <RailButton icon={<FolderTree size={18} />} label="Files" active={activePanel === 'files'} expanded={expanded} onClick={() => toggle('files')} />
-          <RailButton icon={<Search size={18} />} label="Search" shortcut="⌘K" active={activePanel === 'search'} expanded={expanded} onClick={() => toggle('search')} />
-          <RailButton icon={<Blocks size={18} />} label="Plugins" active={activePanel === 'plugins'} expanded={expanded} onClick={() => toggle('plugins')} />
-          <RailButton icon={<Bot size={18} />} label="Agents" active={activePanel === 'agents'} expanded={expanded} onClick={() => toggle('agents')} />
+          <RailButton icon={<FolderTree size={18} />} label={t.sidebar.files} active={activePanel === 'files'} expanded={expanded} onClick={() => toggle('files')} walkthroughId="files-panel" />
+          <RailButton icon={<Search size={18} />} label={t.sidebar.searchTitle} shortcut="⌘K" active={activePanel === 'search'} expanded={expanded} onClick={() => toggle('search')} walkthroughId="search-button" />
+          <RailButton icon={<Blocks size={18} />} label={t.sidebar.plugins} active={activePanel === 'plugins'} expanded={expanded} onClick={() => toggle('plugins')} />
+          <RailButton icon={<Bot size={18} />} label={t.sidebar.agents} active={activePanel === 'agents'} expanded={expanded} onClick={() => toggle('agents')} />
         </div>
 
         {/* ── Spacer ── */}
@@ -140,14 +146,15 @@ export default function ActivityBar({
         <div className={`flex flex-col ${expanded ? 'px-1.5' : 'items-center'} gap-1 py-2`}>
           <RailButton
             icon={<Settings size={18} />}
-            label="Settings"
+            label={t.sidebar.settingsTitle}
             shortcut="⌘,"
             expanded={expanded}
             onClick={() => debounced(onSettingsClick)}
+            walkthroughId="settings-button"
           />
           <RailButton
             icon={<RefreshCw size={18} />}
-            label="Sync"
+            label={t.sidebar.syncLabel}
             expanded={expanded}
             buttonRef={syncBtnRef}
             badge={syncBadge}

package/app/components/GuideCard.tsx

@@ -2,8 +2,10 @@
 
 import { useState, useEffect, useCallback, useRef } from 'react';
 import { X, Sparkles, FolderOpen, MessageCircle, RefreshCw, Check, ChevronRight } from 'lucide-react';
+import Link from 'next/link';
 import { useLocale } from '@/lib/LocaleContext';
 import { openAskModal } from '@/hooks/useAskModal';
+import { walkthroughSteps } from './walkthrough/steps';
 import type { GuideState } from '@/lib/settings';
 
 const DIR_ICONS: Record<string, string> = {
@@ -47,20 +49,18 @@ export default function GuideCard({ onNavigate }: GuideCardProps) {
   useEffect(() => {
     fetchGuideState();
 
-    // ?welcome=1 → first visit, auto-expand explore task
-    const params = new URLSearchParams(window.location.search);
-    if (params.get('welcome') === '1') {
+    // Listen for walkthrough-triggered first visit (WalkthroughProvider owns ?welcome=1 detection)
+    const handleFirstVisit = () => {
       setIsFirstVisit(true);
-      const url = new URL(window.location.href);
-      url.searchParams.delete('welcome');
-      window.history.replaceState({}, '', url.pathname + (url.search || ''));
-    }
+    };
+    window.addEventListener('mindos:first-visit', handleFirstVisit);
 
     // Re-fetch when guide state is updated (e.g. after AskFab patches askedAI)
     const handleGuideUpdate = () => fetchGuideState();
     window.addEventListener('focus', handleGuideUpdate);
     window.addEventListener('guide-state-updated', handleGuideUpdate);
     return () => {
+      window.removeEventListener('mindos:first-visit', handleFirstVisit);
       window.removeEventListener('focus', handleGuideUpdate);
       window.removeEventListener('guide-state-updated', handleGuideUpdate);
     };
@@ -147,6 +147,13 @@ export default function GuideCard({ onNavigate }: GuideCardProps) {
   // Don't render if no active guide
   if (!guideState) return null;
 
+  // Hide GuideCard while walkthrough is active
+  const walkthroughActive = guideState.walkthroughStep !== undefined
+    && guideState.walkthroughStep >= 0
+    && guideState.walkthroughStep < walkthroughSteps.length
+    && !guideState.walkthroughDismissed;
+  if (walkthroughActive) return null;
+
   const step1Done = guideState.step1Done;
   const step2Done = guideState.askedAI;
   const allDone = step1Done && step2Done;
@@ -164,6 +171,13 @@ export default function GuideCard({ onNavigate }: GuideCardProps) {
         <span className="text-sm font-semibold flex-1" style={{ color: 'var(--foreground)' }}>
           ✨ {g.done.titleFinal}
         </span>
+        <Link
+          href="/explore"
+          className="text-xs font-medium transition-colors hover:opacity-80"
+          style={{ color: 'var(--amber)' }}
+        >
+          {t.walkthrough.exploreCta}
+        </Link>
         <button onClick={handleDismiss} className="p-1 rounded hover:bg-muted transition-colors"
           style={{ color: 'var(--muted-foreground)' }}>
           <X size={14} />

package/app/components/HomeContent.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import Link from 'next/link';
-import { FileText, Table, Clock, Sparkles, Puzzle, ArrowRight, FilePlus, Search, ChevronDown } from 'lucide-react';
+import { FileText, Table, Clock, Sparkles, Puzzle, ArrowRight, FilePlus, Search, ChevronDown, Compass } from 'lucide-react';
 import { useState, useEffect, useRef } from 'react';
 import { useLocale } from '@/lib/LocaleContext';
 import { encodePath, relativeTime } from '@/lib/utils';
@@ -94,6 +94,7 @@ export default function HomeContent({ recent, existingFiles }: { recent: RecentF
           <button
             onClick={triggerAsk}
             title="⌘/"
+            data-walkthrough="ask-button"
             className="flex-1 flex items-center gap-3 px-4 py-3 rounded-xl border transition-all duration-150 hover:border-amber-500/50 hover:bg-amber-500/8"
             style={{ background: 'var(--card)', borderColor: 'var(--border)' }}
           >
@@ -153,6 +154,16 @@ export default function HomeContent({ recent, existingFiles }: { recent: RecentF
             <FilePlus size={14} />
             <span>{t.home.newNote}</span>
           </Link>
+          <Link
+            href="/explore"
+            className="inline-flex items-center gap-2 px-3.5 py-2 rounded-lg text-sm font-medium transition-all duration-150 hover:translate-x-0.5"
+            style={{
+              color: 'var(--amber)',
+            }}
+          >
+            <Compass size={14} />
+            <span>{t.explore.title}</span>
+          </Link>
         </div>
 
       </div>

package/app/components/KeyboardShortcuts.tsx

@@ -0,0 +1,102 @@
+'use client';
+
+import { useState, useEffect, useMemo } from 'react';
+import { X } from 'lucide-react';
+import { useLocale } from '@/lib/LocaleContext';
+
+export default function KeyboardShortcuts() {
+  const [open, setOpen] = useState(false);
+  const { t } = useLocale();
+  const s = t.shortcutPanel;
+
+  const isMac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.userAgent);
+  const mod = isMac ? '⌘' : 'Ctrl';
+
+  const shortcuts = useMemo(() => [
+    { keys: `${mod} K`, label: s.toggleSearch, section: s.navigation },
+    { keys: `${mod} /`, label: s.toggleAskAI, section: s.navigation },
+    { keys: `${mod} ,`, label: s.openSettings, section: s.navigation },
+    { keys: `${mod} ?`, label: s.keyboardShortcuts, section: s.navigation },
+    { keys: 'Esc', label: s.closePanel, section: s.panelsSection },
+    { keys: `${mod} S`, label: s.saveFile, section: s.editor },
+    { keys: `${mod} Z`, label: s.undo, section: s.editor },
+    { keys: `${mod} Shift Z`, label: s.redo, section: s.editor },
+  ], [mod, s]);
+
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.shiftKey && e.key === '/') {
+        e.preventDefault();
+        setOpen(v => !v);
+      }
+      if (e.key === 'Escape' && open) {
+        setOpen(false);
+      }
+    };
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, [open]);
+
+  if (!open) return null;
+
+  const sections = [...new Set(shortcuts.map(s => s.section))];
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center modal-backdrop"
+      onClick={e => e.target === e.currentTarget && setOpen(false)}
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label={s.title}
+        className="w-full max-w-md mx-4 bg-card border border-border rounded-xl shadow-2xl overflow-hidden"
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between px-5 py-3.5 border-b border-border">
+          <span className="text-sm font-medium font-display text-foreground">{s.title}</span>
+          <button
+            onClick={() => setOpen(false)}
+            className="p-1 rounded hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
+          >
+            <X size={15} />
+          </button>
+        </div>
+
+        {/* Content */}
+        <div className="px-5 py-4 space-y-4 max-h-[60vh] overflow-y-auto">
+          {sections.map(section => (
+            <div key={section}>
+              <h3 className="text-[11px] font-medium text-muted-foreground uppercase tracking-wider mb-2">{section}</h3>
+              <div className="space-y-1">
+                {shortcuts.filter(s => s.section === section).map(s => (
+                  <div key={s.keys} className="flex items-center justify-between py-1.5">
+                    <span className="text-xs text-foreground">{s.label}</span>
+                    <div className="flex items-center gap-1">
+                      {s.keys.split(' ').map((key, i) => (
+                        <kbd
+                          key={i}
+                          className="px-1.5 py-0.5 text-2xs rounded border border-border bg-muted text-muted-foreground font-mono min-w-[24px] text-center"
+                        >
+                          {key}
+                        </kbd>
+                      ))}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            </div>
+          ))}
+        </div>
+
+        {/* Footer */}
+        <div className="px-5 py-2.5 border-t border-border">
+          <p className="text-2xs text-muted-foreground/60">
+            Press <kbd className="px-1 py-0.5 text-2xs rounded border border-border bg-muted font-mono">{mod}</kbd>
+            <kbd className="px-1 py-0.5 text-2xs rounded border border-border bg-muted font-mono ml-0.5">?</kbd> {s.toggleHint}
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+}

package/app/components/Panel.tsx

@@ -8,6 +8,9 @@ import FileTree from './FileTree';
 import SyncStatusBar from './SyncStatusBar';
 import PanelHeader from './panels/PanelHeader';
 import { useResizeDrag } from '@/hooks/useResizeDrag';
+import { useLocale } from '@/lib/LocaleContext';
+
+const noop = () => {};
 
 /** Compute the maximum directory depth of a file tree */
 function getMaxDepth(nodes: FileNode[], current = 0): number {
@@ -68,6 +71,8 @@ export default function Panel({
   const defaultWidth = activePanel ? DEFAULT_PANEL_WIDTH[activePanel] : 280;
   const width = maximized ? undefined : (panelWidth ?? defaultWidth);
 
+  const { t } = useLocale();
+
   // File tree depth control: null = manual (no override), number = forced max open depth
   const [maxOpenDepth, setMaxOpenDepth] = useState<number | null>(null);
   const treeMaxDepth = useMemo(() => getMaxDepth(fileTree), [fileTree]);
@@ -79,8 +84,8 @@ export default function Panel({
     maxWidthRatio: MAX_PANEL_WIDTH_RATIO,
     direction: 'right',
     disabled: maximized,
-    onResize: onWidthChange ?? (() => {}),
-    onResizeEnd: onWidthCommit ?? (() => {}),
+    onResize: onWidthChange ?? noop,
+    onResizeEnd: onWidthCommit ?? noop,
   });
 
   return (
@@ -97,7 +102,7 @@ export default function Panel({
     >
       {/* Files panel — always mounted to preserve tree expand/collapse state */}
       <div className={`flex flex-col h-full ${activePanel === 'files' ? '' : 'hidden'}`}>
-        <PanelHeader title="Files">
+        <PanelHeader title={t.sidebar.files}>
           <div className="flex items-center gap-0.5">
             <button
               onClick={() => setMaxOpenDepth(prev => {
@@ -105,8 +110,8 @@ export default function Panel({
                 return Math.max(-1, current - 1);
               })}
               className="p-1 rounded hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
-              aria-label="Collapse one level"
-              title="Collapse one level"
+              aria-label={t.sidebar.collapseLevel}
+              title={t.sidebar.collapseLevel}
             >
               <ChevronsDownUp size={13} />
             </button>
@@ -120,8 +125,8 @@ export default function Panel({
                 return next;
               })}
               className="p-1 rounded hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
-              aria-label="Expand one level"
-              title="Expand one level"
+              aria-label={t.sidebar.expandLevel}
+              title={t.sidebar.expandLevel}
             >
               <ChevronsUpDown size={13} />
             </button>

package/app/components/SidebarLayout.tsx

@@ -17,10 +17,12 @@ import SyncPopover from './panels/SyncPopover';
 import SearchModal from './SearchModal';
 import AskModal from './AskModal';
 import SettingsModal from './SettingsModal';
+import KeyboardShortcuts from './KeyboardShortcuts';
 import { MobileSyncDot, useSyncStatus } from './SyncStatusBar';
 import { useAskModal } from '@/hooks/useAskModal';
 import { FileNode } from '@/lib/types';
 import { useLocale } from '@/lib/LocaleContext';
+import { WalkthroughProvider } from './walkthrough';
 import type { Tab } from './settings/types';
 
 interface SidebarLayoutProps {
@@ -177,6 +179,17 @@ export default function SidebarLayout({ fileTree, children }: SidebarLayoutProps
     try { localStorage.setItem('rail-expanded', String(expanded)); } catch {}
   }, []);
 
+  // Listen for cross-component "open settings" events (e.g. from UpdateBanner)
+  useEffect(() => {
+    const handler = (e: Event) => {
+      const tab = (e as CustomEvent).detail?.tab;
+      if (tab) setSettingsTab(tab);
+      setSettingsOpen(true);
+    };
+    window.addEventListener('mindos:open-settings', handler);
+    return () => window.removeEventListener('mindos:open-settings', handler);
+  }, []);
+
   // Bridge useAskModal store → right Ask panel or popup
   useEffect(() => {
     if (askModal.open) {
@@ -290,6 +303,7 @@ export default function SidebarLayout({ fileTree, children }: SidebarLayoutProps
   const effectivePanelWidth = panelWidth ?? (activePanel ? PANEL_WIDTH[activePanel] : 280);
 
   return (
+    <WalkthroughProvider>
     <>
       {/* Skip link */}
       <a
@@ -335,7 +349,6 @@ export default function SidebarLayout({ fileTree, children }: SidebarLayoutProps
             active={activePanel === 'agents'}
             maximized={panelMaximized}
             onMaximize={handlePanelMaximize}
-            onOpenSettings={openSettingsTab}
           />
         </div>
       </Panel>
@@ -368,6 +381,9 @@ export default function SidebarLayout({ fileTree, children }: SidebarLayoutProps
       {/* ── Ask AI FAB (desktop only — toggles right panel or popup) ── */}
       <AskFab onToggle={toggleAskPanel} askPanelOpen={askPanelOpen || desktopAskPopupOpen} />
 
+      {/* ── Keyboard Shortcuts (⌘?) ── */}
+      <KeyboardShortcuts />
+
       {/* ── Settings Modal (desktop overlay — does not affect panel) ── */}
       <SettingsModal
         open={settingsOpen}
@@ -455,5 +471,6 @@ export default function SidebarLayout({ fileTree, children }: SidebarLayoutProps
         }
       `}</style>
     </>
+    </WalkthroughProvider>
   );
 }

package/app/components/UpdateBanner.tsx

@@ -45,6 +45,13 @@ export default function UpdateBanner() {
     setInfo(null);
   };
 
+  const handleOpenUpdate = () => {
+    window.dispatchEvent(new CustomEvent('mindos:open-settings', { detail: { tab: 'update' } }));
+    // Dismiss banner once user engages with Update tab
+    localStorage.setItem('mindos_update_dismissed', info.latest);
+    setInfo(null);
+  };
+
   const updateT = t.updateBanner;
 
   return (
@@ -58,32 +65,23 @@ export default function UpdateBanner() {
             ? updateT.newVersion(info.latest, info.current)
             : `MindOS v${info.latest} available (current: v${info.current})`}
         </span>
-        <span className="text-muted-foreground">
-          {updateT?.runUpdate ?? 'Run'}{' '}
-          <code className="px-1 py-0.5 rounded bg-muted font-mono text-xs">mindos update</code>
+        <button
+          onClick={handleOpenUpdate}
+          className="px-2 py-0.5 rounded-md text-xs font-medium text-white transition-colors hover:opacity-90"
+          style={{ background: 'var(--amber)' }}
+        >
+          {updateT?.updateNow ?? 'Update'}
+        </button>
+        <span className="text-muted-foreground hidden sm:inline">
           {updateT?.orSee ? (
             <>
-              {' '}{updateT.orSee}{' '}
-              <a
-                href="https://github.com/GeminiLight/mindos/releases"
-                target="_blank"
-                rel="noopener noreferrer"
-                className="underline hover:text-foreground transition-colors"
-              >
-                {updateT.releaseNotes}
-              </a>
+              {updateT.orSee}{' '}
+              <a href="https://github.com/GeminiLight/mindos/releases" target="_blank" rel="noopener noreferrer" className="underline hover:text-foreground transition-colors">{updateT.releaseNotes}</a>
             </>
           ) : (
             <>
-              {' '}or{' '}
-              <a
-                href="https://github.com/GeminiLight/mindos/releases"
-                target="_blank"
-                rel="noopener noreferrer"
-                className="underline hover:text-foreground transition-colors"
-              >
-                view release notes
-              </a>
+              or{' '}
+              <a href="https://github.com/GeminiLight/mindos/releases" target="_blank" rel="noopener noreferrer" className="underline hover:text-foreground transition-colors">release notes</a>
             </>
           )}
         </span>

package/app/components/explore/ExploreContent.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+import { useState } from 'react';
+import { useLocale } from '@/lib/LocaleContext';
+import { useCases, categories, type UseCaseCategory } from './use-cases';
+import UseCaseCard from './UseCaseCard';
+
+export default function ExploreContent() {
+  const { t } = useLocale();
+  const e = t.explore;
+  const [activeCategory, setActiveCategory] = useState<UseCaseCategory | 'all'>('all');
+
+  const filtered = activeCategory === 'all'
+    ? useCases
+    : useCases.filter(uc => uc.category === activeCategory);
+
+  /** Type-safe lookup for use case i18n data by id */
+  const getUseCaseText = (id: string): { title: string; desc: string; prompt: string } | undefined => {
+    const map: Record<string, { title: string; desc: string; prompt: string }> = {
+      c1: e.c1, c2: e.c2, c3: e.c3, c4: e.c4, c5: e.c5,
+      c6: e.c6, c7: e.c7, c8: e.c8, c9: e.c9,
+    };
+    return map[id];
+  };
+
+  return (
+    <div className="content-width px-4 md:px-6 py-8 md:py-12">
+      {/* Header */}
+      <div className="mb-8">
+        <div className="flex items-center gap-2 mb-3">
+          <div className="w-1 h-5 rounded-full" style={{ background: 'var(--amber)' }} />
+          <h1
+            className="text-2xl font-semibold tracking-tight font-display"
+            style={{ color: 'var(--foreground)' }}
+          >
+            {e.title}
+          </h1>
+        </div>
+        <p
+          className="text-sm leading-relaxed"
+          style={{ color: 'var(--muted-foreground)', paddingLeft: '1rem' }}
+        >
+          {e.subtitle}
+        </p>
+      </div>
+
+      {/* Category tabs */}
+      <div className="flex flex-wrap gap-2 mb-6" style={{ paddingLeft: '1rem' }}>
+        <CategoryChip
+          label={e.all}
+          active={activeCategory === 'all'}
+          onClick={() => setActiveCategory('all')}
+        />
+        {categories.map(cat => (
+          <CategoryChip
+            key={cat}
+            label={(e.categories as Record<string, string>)[cat]}
+            active={activeCategory === cat}
+            onClick={() => setActiveCategory(cat)}
+          />
+        ))}
+      </div>
+
+      {/* Card grid */}
+      <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3" style={{ paddingLeft: '1rem' }}>
+        {filtered.map(uc => {
+          const data = getUseCaseText(uc.id);
+          if (!data) return null;
+          return (
+            <UseCaseCard
+              key={uc.id}
+              icon={uc.icon}
+              title={data.title}
+              description={data.desc}
+              prompt={data.prompt}
+              tryItLabel={e.tryIt}
+            />
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+function CategoryChip({ label, active, onClick }: { label: string; active: boolean; onClick: () => void }) {
+  return (
+    <button
+      onClick={onClick}
+      className={`
+        px-3 py-1.5 rounded-full text-xs font-medium transition-all duration-150
+        ${active
+          ? 'text-[var(--amber)] bg-[var(--amber-dim)]'
+          : 'text-[var(--muted-foreground)] bg-[var(--muted)] hover:text-[var(--foreground)] hover:bg-[var(--muted)]/80'
+        }
+      `}
+    >
+      {label}
+    </button>
+  );
+}

package/app/components/explore/UseCaseCard.tsx

@@ -0,0 +1,50 @@
+'use client';
+
+import { openAskModal } from '@/hooks/useAskModal';
+
+interface UseCaseCardProps {
+  icon: string;
+  title: string;
+  description: string;
+  prompt: string;
+  tryItLabel: string;
+}
+
+export default function UseCaseCard({ icon, title, description, prompt, tryItLabel }: UseCaseCardProps) {
+  return (
+    <div
+      className="group flex flex-col gap-3 p-4 rounded-xl border transition-all duration-150 hover:border-amber-500/30 hover:bg-muted/50"
+      style={{ borderColor: 'var(--border)', background: 'var(--card)' }}
+    >
+      <div className="flex items-start gap-3">
+        <span className="text-xl leading-none shrink-0 mt-0.5" suppressHydrationWarning>
+          {icon}
+        </span>
+        <div className="flex-1 min-w-0">
+          <h3
+            className="text-sm font-semibold font-display truncate"
+            style={{ color: 'var(--foreground)' }}
+          >
+            {title}
+          </h3>
+          <p
+            className="text-xs leading-relaxed mt-1 line-clamp-2"
+            style={{ color: 'var(--muted-foreground)' }}
+          >
+            {description}
+          </p>
+        </div>
+      </div>
+      <button
+        onClick={() => openAskModal(prompt, 'user')}
+        className="self-start inline-flex items-center gap-1.5 px-3 py-1.5 rounded-lg text-xs font-medium transition-all duration-150 hover:opacity-80 cursor-pointer"
+        style={{
+          background: 'var(--amber-dim)',
+          color: 'var(--amber)',
+        }}
+      >
+        {tryItLabel} →
+      </button>
+    </div>
+  );
+}