From 9106d95fccfba4e2dda7fe4d6273251176cb097f Mon Sep 17 00:00:00 2001
From: Abhinaysai Kamineni <kamineniabhinaysai@gmail.com>
Date: Thu, 25 Jun 2026 12:04:40 -0400
Subject: [PATCH 1/2] Improve first-run onboarding and Connection workspace UX.

Add a four-step onboarding flow, persist settings under cortex_settings_v2,
surface workspace presets and live-demo context on Home, and wire replay tour.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../components/onboarding/OnboardingModal.tsx | 175 ++++++++++++++----
 frontend/src/lib/onboarding.ts                |  22 ++-
 frontend/src/lib/settings.ts                  |  54 ++++++
 frontend/src/views/HomeView.tsx               | 153 ++++++++-------
 4 files changed, 300 insertions(+), 104 deletions(-)
 create mode 100644 frontend/src/lib/settings.ts

diff --git a/frontend/src/components/onboarding/OnboardingModal.tsx b/frontend/src/components/onboarding/OnboardingModal.tsx
index f4a0ac4..4b432d8 100644
--- a/frontend/src/components/onboarding/OnboardingModal.tsx
+++ b/frontend/src/components/onboarding/OnboardingModal.tsx
@@ -1,69 +1,174 @@
 import { useState } from "react";
 import { markOnboardingComplete } from "../../lib/onboarding";
+import { useApp } from "../../context/AppContext";
+import { IconSpark } from "../ui/icons";
 
 type Props = {
   onComplete: () => void;
   onOpenCopilot: () => void;
+  onFinishAsk: (workspace: string, query: string) => void;
 };
 
-const STEPS = [
-  {
-    title: "Your organization's living memory",
-    body: "Cortex captures decisions — not documents — from Slack, GitHub, Jira, and more. Ask natural questions and get answers with who decided, why, and what's affected.",
-    icon: "◈",
-  },
-  {
-    title: "Ask in plain language",
-    body: 'Try questions like "Why did we choose CockroachDB for payments?" or "What affects checkout?" Cortex searches structured memory, not scattered threads.',
-    icon: "?",
-  },
-  {
-    title: "Meet Assist",
-    body: "Cortex Assist guides you, runs searches, and explains results. Use the memory map to see how people, systems, and decisions connect over time.",
-    icon: "✦",
-  },
+const WORKSPACE_PRESETS = [
+  { id: "local-dev", label: "Demo workspace", hint: "Pre-seeded decisions for demos" },
+  { id: "oss-tiangolo-fastapi", label: "OSS: FastAPI", hint: "Open-source graph import" },
+  { id: "oss-adr", label: "OSS: ADRs", hint: "Architecture decision records" },
 ] as const;
 
-export function OnboardingModal({ onComplete, onOpenCopilot }: Props) {
+const DEMO_QUERY = "Why CockroachDB for payments?";
+
+export function OnboardingModal({ onComplete, onOpenCopilot, onFinishAsk }: Props) {
+  const { setWorkspaceId, apiKey, setApiKey, saveApiKey } = useApp();
   const [step, setStep] = useState(0);
-  const current = STEPS[step];
-  const isLast = step === STEPS.length - 1;
+  const [workspace, setWorkspace] = useState("local-dev");
+  const isLast = step === 3;
 
-  function finish() {
-    markOnboardingComplete();
+  function finishToAsk(): void {
+    markOnboardingComplete(workspace);
+    setWorkspaceId(workspace);
     onComplete();
-    if (isLast) onOpenCopilot();
+    onFinishAsk(workspace, DEMO_QUERY);
+  }
+
+  function finishToAssist(): void {
+    markOnboardingComplete(workspace);
+    setWorkspaceId(workspace);
+    onComplete();
+    onOpenCopilot();
   }
 
   return (
-    <div className="onboarding-overlay" role="dialog" aria-modal="true" aria-labelledby="onboarding-title">
+    <div
+      className="onboarding-overlay"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="onboarding-title"
+    >
       <div className="onboarding-modal">
         <div className="onboarding-modal__progress" aria-hidden>
-          {STEPS.map((_, i) => (
+          {[0, 1, 2, 3].map((i) => (
             <span key={i} className={`onboarding-dot ${i <= step ? "onboarding-dot--active" : ""}`} />
           ))}
         </div>
-        <span className="onboarding-modal__icon" aria-hidden>
-          {current.icon}
-        </span>
-        <h2 id="onboarding-title" className="onboarding-modal__title">
-          {current.title}
-        </h2>
-        <p className="onboarding-modal__body">{current.body}</p>
+
+        {step === 0 ? (
+          <>
+            <span className="onboarding-modal__icon" aria-hidden>
+              ◈
+            </span>
+            <h2 id="onboarding-title" className="onboarding-modal__title">
+              Your organization's living memory
+            </h2>
+            <p className="onboarding-modal__body">
+              Cortex captures <strong>decisions</strong> — not documents — from Slack, GitHub, Jira,
+              and more. Ask natural questions and get answers with who decided, why, and what's
+              affected.
+            </p>
+          </>
+        ) : null}
+
+        {step === 1 ? (
+          <>
+            <h2 id="onboarding-title" className="onboarding-modal__title">
+              Choose a workspace
+            </h2>
+            <p className="onboarding-modal__body">
+              Workspaces isolate organizational memory. Start with the demo workspace or pick an OSS
+              preset.
+            </p>
+            <div className="onboarding-workspaces">
+              {WORKSPACE_PRESETS.map((w) => (
+                <button
+                  key={w.id}
+                  type="button"
+                  className={`onboarding-workspace ${workspace === w.id ? "onboarding-workspace--active" : ""}`}
+                  onClick={() => setWorkspace(w.id)}
+                >
+                  <span className="onboarding-workspace__label">{w.label}</span>
+                  <span className="onboarding-workspace__hint">{w.hint}</span>
+                </button>
+              ))}
+            </div>
+          </>
+        ) : null}
+
+        {step === 2 ? (
+          <>
+            <h2 id="onboarding-title" className="onboarding-modal__title">
+              Try a demo search
+            </h2>
+            <p className="onboarding-modal__body">
+              We'll open Search with a sample question so you can see trust scores, coverage, and
+              decision stories in seconds.
+            </p>
+            <blockquote className="onboarding-query">{DEMO_QUERY}</blockquote>
+          </>
+        ) : null}
+
+        {step === 3 ? (
+          <>
+            <h2 id="onboarding-title" className="onboarding-modal__title">
+              Connection (optional)
+            </h2>
+            <p className="onboarding-modal__body">
+              The public demo works without a key. If your deployment requires authentication, add
+              your API key now — you can always change it under Connection later.
+            </p>
+            <label className="field-label" htmlFor="onboard-api-key">
+              API key
+            </label>
+            <input
+              id="onboard-api-key"
+              className="input"
+              type="password"
+              value={apiKey}
+              onChange={(e) => setApiKey(e.target.value)}
+              placeholder="Optional"
+              autoComplete="off"
+            />
+          </>
+        ) : null}
+
         <footer className="onboarding-modal__actions">
           {step > 0 ? (
             <button type="button" className="btn btn--ghost" onClick={() => setStep((s) => s - 1)}>
               Back
             </button>
           ) : (
-            <button type="button" className="btn btn--ghost" onClick={finish}>
+            <button
+              type="button"
+              className="btn btn--ghost"
+              onClick={() => {
+                markOnboardingComplete(workspace);
+                onComplete();
+              }}
+            >
               Skip tour
             </button>
           )}
           {isLast ? (
-            <button type="button" className="btn btn--primary" onClick={finish}>
-              Open Assist
-            </button>
+            <>
+              <button
+                type="button"
+                className="btn btn--secondary"
+                onClick={() => {
+                  if (apiKey.trim()) saveApiKey();
+                  finishToAsk();
+                }}
+              >
+                Search memory
+              </button>
+              <button
+                type="button"
+                className="btn btn--primary"
+                onClick={() => {
+                  if (apiKey.trim()) saveApiKey();
+                  finishToAssist();
+                }}
+              >
+                <IconSpark size={16} aria-hidden /> Open Assist
+              </button>
+            </>
           ) : (
             <button type="button" className="btn btn--primary" onClick={() => setStep((s) => s + 1)}>
               Continue
diff --git a/frontend/src/lib/onboarding.ts b/frontend/src/lib/onboarding.ts
index b08309f..892fa9b 100644
--- a/frontend/src/lib/onboarding.ts
+++ b/frontend/src/lib/onboarding.ts
@@ -1,17 +1,29 @@
-const STORAGE_KEY = "cortex_onboarding_v1";
+import { loadSettings, saveSettings } from "./settings";
+
+const LEGACY_KEY = "cortex_onboarding_v1";
 
 export function hasCompletedOnboarding(): boolean {
   try {
-    return localStorage.getItem(STORAGE_KEY) === "done";
+    const settings = loadSettings();
+    if (settings.onboardingComplete) return true;
+    return localStorage.getItem(LEGACY_KEY) === "done";
   } catch {
     return false;
   }
 }
 
-export function markOnboardingComplete(): void {
+export function markOnboardingComplete(workspaceId?: string): void {
+  saveSettings({
+    onboardingComplete: true,
+    ...(workspaceId ? { workspaceId } : {}),
+  });
+}
+
+export function resetOnboarding(): void {
+  saveSettings({ onboardingComplete: false });
   try {
-    localStorage.setItem(STORAGE_KEY, "done");
+    localStorage.removeItem(LEGACY_KEY);
   } catch {
-    // Private browsing — skip persistence.
+    // ignore
   }
 }
diff --git a/frontend/src/lib/settings.ts b/frontend/src/lib/settings.ts
new file mode 100644
index 0000000..f394b7a
--- /dev/null
+++ b/frontend/src/lib/settings.ts
@@ -0,0 +1,54 @@
+const STORAGE_KEY = "cortex_settings_v2";
+
+export type CortexSettings = {
+  onboardingComplete: boolean;
+  workspaceId: string;
+};
+
+const DEFAULTS: CortexSettings = {
+  onboardingComplete: false,
+  workspaceId: "local-dev",
+};
+
+export function loadSettings(): CortexSettings {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) {
+      const legacyOnboarding = localStorage.getItem("cortex_onboarding_v1") === "done";
+      const legacyWorkspace = localStorage.getItem("cortex_workspace_id")?.trim();
+      return {
+        onboardingComplete: legacyOnboarding,
+        workspaceId: legacyWorkspace || DEFAULTS.workspaceId,
+      };
+    }
+    const parsed = JSON.parse(raw) as Partial<CortexSettings>;
+    return {
+      onboardingComplete: Boolean(parsed.onboardingComplete),
+      workspaceId: String(parsed.workspaceId || DEFAULTS.workspaceId),
+    };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+export function saveSettings(patch: Partial<CortexSettings>): CortexSettings {
+  const next = { ...loadSettings(), ...patch };
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(next));
+    if (next.onboardingComplete) {
+      localStorage.setItem("cortex_onboarding_v1", "done");
+    }
+    if (next.workspaceId) {
+      localStorage.setItem("cortex_workspace_id", next.workspaceId);
+    }
+  } catch {
+    // Private browsing — skip persistence.
+  }
+  return next;
+}
+
+export function isLiveDemoHost(): boolean {
+  if (typeof window === "undefined") return false;
+  const host = window.location.hostname;
+  return host.endsWith(".vercel.app") || host.includes("cortex");
+}
diff --git a/frontend/src/views/HomeView.tsx b/frontend/src/views/HomeView.tsx
index b154e32..87e3343 100644
--- a/frontend/src/views/HomeView.tsx
+++ b/frontend/src/views/HomeView.tsx
@@ -4,12 +4,15 @@ import type { DecisionResult, Health } from "../types";
 import { useApp } from "../context/AppContext";
 import { buildDashboardMetrics, trustHeadline } from "../lib/insights";
 import { scorePercent } from "../lib/format";
+import { isLiveDemoHost } from "../lib/settings";
 import { PageHeader } from "../components/ui/PageHeader";
 import { MetricCard } from "../components/ui/MetricCard";
 import { DecisionTeaser } from "../components/dashboard/DecisionTeaser";
 import { MemoryGraph } from "../components/memory/MemoryGraph";
-import { Skeleton } from "../components/ui/Skeleton";
+import { WorkspaceBar } from "../components/layout/WorkspaceBar";
+import { SkeletonStack } from "../components/ui/Skeleton";
 import { StateView } from "../components/ui/StateView";
+import { IconEmpty } from "../components/ui/icons";
 
 export function HomeView() {
   const {
@@ -19,11 +22,13 @@ export function HomeView() {
     setLastQuery,
     workspaceId,
     setAssistantOpen,
+    lastQuery,
   } = useApp();
   const [decisions, setDecisions] = useState<DecisionResult[]>([]);
   const [health, setHealth] = useState<Health | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
+  const [metrics, setMetrics] = useState(() => buildDashboardMetrics([], []));
 
   const load = useCallback(async () => {
     setLoading(true);
@@ -31,7 +36,11 @@ export function HomeView() {
     const ws = workspaceId.trim() || "local-dev";
     try {
       const [queryRes, contradictions, healthRes] = await Promise.all([
-        queryMemory({ query: "organizational decisions architecture payments", workspace_id: ws, limit: 12 }),
+        queryMemory({
+          query: "organizational decisions architecture payments",
+          workspace_id: ws,
+          limit: 12,
+        }),
         fetchContradictions(ws).catch(() => []),
         fetchHealth().catch(() => null),
       ]);
@@ -50,17 +59,35 @@ export function HomeView() {
     }
   }, [workspaceId, setLastQuery, setExploreDecisions, setSelectedDecisionId]);
 
-  const [metrics, setMetrics] = useState(() =>
-    buildDashboardMetrics([], []),
-  );
-
   useEffect(() => {
     void load();
   }, [load]);
 
   function openDecision(id: string) {
     setSelectedDecisionId(id);
-    setView("explore");
+    setView("explore", { decision: id });
+  }
+
+  const coverage =
+    typeof lastQuery?.coverage_score === "number"
+      ? lastQuery.coverage_score
+      : metrics.decisionCount > 0
+        ? 0.45
+        : 0;
+
+  if (loading && !decisions.length && !error) {
+    return (
+      <article className="view view--home fade-in">
+        <PageHeader
+          eyebrow="Organizational intelligence"
+          title="See what your team decided — and why it matters"
+          subtitle="A living memory of decisions across Slack, GitHub, Jira, and more."
+        />
+        <WorkspaceBar />
+        <SkeletonStack rows={4} variant="card" />
+        <SkeletonStack rows={2} variant="row" />
+      </article>
+    );
   }
 
   return (
@@ -90,67 +117,68 @@ export function HomeView() {
         }
       />
 
+      {isLiveDemoHost() ? (
+        <p className="live-demo-banner panel" role="note">
+          <strong>Live demo</strong> — connected to Cortex cloud memory. Try Search or open
+          Connection to point at your own API.
+        </p>
+      ) : null}
+
+      <WorkspaceBar />
+
       {error ? (
-        <StateView tone="error" icon="!" title="Can't load organizational memory" action={
-          <button type="button" className="btn btn--secondary" onClick={() => void load()}>
-            Retry
-          </button>
-        }>
+        <StateView
+          tone="error"
+          title="Can't load organizational memory"
+          action={
+            <button type="button" className="btn btn--secondary" onClick={() => void load()}>
+              Retry
+            </button>
+          }
+        >
           {error}
         </StateView>
       ) : null}
 
-      {loading ? (
-        <div className="metrics-row" aria-hidden>
-          {Array.from({ length: 4 }, (_, i) => (
-            <Skeleton key={i} variant="card" />
-          ))}
-        </div>
-      ) : (
-        <section className="metrics-row" aria-label="Executive summary">
-          <MetricCard
-            icon="◈"
-            label="Decisions in view"
-            value={String(metrics.decisionCount)}
-            hint="Captured organizational memory"
-            tone="accent"
-          />
-          <MetricCard
-            icon="◎"
-            label="Memory confidence"
-            value={trustHeadline(metrics.avgTrust)}
-            hint={metrics.decisionCount ? `${scorePercent(metrics.avgTrust)}% avg trust` : "Search to populate"}
-            tone="ok"
-          />
-          <MetricCard
-            icon="⚡"
-            label="Avg impact"
-            value={metrics.decisionCount ? `${scorePercent(metrics.avgImpact)}%` : "—"}
-            hint="Importance across decisions"
-          />
-          <MetricCard
-            icon="⚖"
-            label="Open conflicts"
-            value={String(metrics.pendingConflicts)}
-            hint={metrics.pendingConflicts ? "Needs review" : "Graph is consistent"}
-            tone={metrics.pendingConflicts ? "warn" : "ok"}
-          />
-        </section>
-      )}
+      <section className="metrics-row" aria-label="Executive summary">
+        <MetricCard
+          icon="◈"
+          label="Decisions in view"
+          value={String(metrics.decisionCount)}
+          hint="Captured organizational memory"
+          tone="accent"
+        />
+        <MetricCard
+          icon="◎"
+          label="Memory confidence"
+          value={trustHeadline(metrics.avgTrust)}
+          hint={metrics.decisionCount ? `${scorePercent(metrics.avgTrust)}% avg trust` : "Search to populate"}
+          tone="ok"
+        />
+        <MetricCard
+          icon="◇"
+          label="Coverage"
+          value={metrics.decisionCount ? `${Math.round(coverage * 100)}%` : "—"}
+          hint="How complete memory is for this workspace"
+          tone="accent"
+        />
+        <MetricCard
+          icon="⚖"
+          label="Open conflicts"
+          value={String(metrics.pendingConflicts)}
+          hint={metrics.pendingConflicts ? "Needs review" : "Graph is consistent"}
+          tone={metrics.pendingConflicts ? "warn" : "ok"}
+        />
+      </section>
 
       <div className="dashboard-grid">
         <section className="dashboard-panel" aria-labelledby="recent-decisions">
           <h2 id="recent-decisions" className="dashboard-panel__title">
             Recent decisions
           </h2>
-          {loading ? (
-            <>
-              <Skeleton variant="row" />
-              <Skeleton variant="row" />
-            </>
-          ) : metrics.recentDecisions.length === 0 ? (
+          {metrics.recentDecisions.length === 0 ? (
             <StateView
-              icon="◇"
+              icon={<IconEmpty size={28} />}
               title="No decisions yet"
               action={
                 <button type="button" className="btn btn--primary" onClick={() => setView("ask")}>
@@ -158,7 +186,8 @@ export function HomeView() {
                 </button>
               }
             >
-              Run <code>make demo</code> to seed example memories, or capture a decision from the AI agents view.
+              Connect your tools or capture a decision from AI agents — then search to see
+              organizational memory here.
             </StateView>
           ) : (
             <div className="decision-feed">
@@ -168,7 +197,7 @@ export function HomeView() {
             </div>
           )}
           {metrics.recentDecisions.length > 0 ? (
-            <footer style={{ marginTop: "var(--space-4)" }}>
+            <footer className="dashboard-panel__foot">
               <button type="button" className="btn btn--ghost" onClick={() => setView("explore")}>
                 Open full memory map →
               </button>
@@ -199,9 +228,7 @@ export function HomeView() {
 
           {metrics.activePeople.length > 0 ? (
             <>
-              <h3 className="field-label" style={{ marginTop: "var(--space-4)" }}>
-                Active decision makers
-              </h3>
+              <h3 className="field-label dashboard-panel__subhead">Active decision makers</h3>
               <div className="people-chips">
                 {metrics.activePeople.map((p) => (
                   <span key={p} className="people-chip">
@@ -214,9 +241,7 @@ export function HomeView() {
 
           {decisions.length > 0 ? (
             <div className="dashboard-graph-preview">
-              <h3 className="field-label" style={{ marginTop: "var(--space-4)" }}>
-                Knowledge graph preview
-              </h3>
+              <h3 className="field-label dashboard-panel__subhead">Knowledge graph preview</h3>
               <MemoryGraph
                 decisions={decisions.slice(0, 6)}
                 focusId={decisions[0]?.event_id}

From c58c96eef3efb6d86e59dace7e1c6a852ddfe9ae Mon Sep 17 00:00:00 2001
From: Abhinaysai Kamineni <kamineniabhinaysai@gmail.com>
Date: Thu, 25 Jun 2026 13:13:04 -0400
Subject: [PATCH 2/2] fix(frontend): wire onboarding context and routing for
 stacked PR20 build

Restore App, AppContext, and hash routing needed by onboarding v2 and
HomeView deep links after PR18 scope isolation. Include optional
coverage_score on QueryResponse used by Home metrics.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 frontend/src/App.tsx                          | 16 ++--
 .../src/components/layout/WorkspaceBar.tsx    | 14 ++--
 frontend/src/context/AppContext.tsx           | 79 ++++++++++++++++---
 frontend/src/lib/routing.ts                   | 44 +++++++++--
 frontend/src/types/index.ts                   |  1 +
 5 files changed, 125 insertions(+), 29 deletions(-)

diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 3bea1ef..5461cae 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -1,4 +1,4 @@
-import { Suspense, lazy, useState } from "react";
+import { Suspense, lazy } from "react";
 import { AppProvider, useApp } from "./context/AppContext";
 import { ToastProvider } from "./components/ui/Toast";
 import { ErrorBoundary } from "./components/ui/ErrorBoundary";
@@ -11,9 +11,9 @@ import { AskView } from "./views/AskView";
 import { SkeletonStack } from "./components/ui/Skeleton";
 import { apiBase } from "./api/client";
 import { resolveApiKey } from "./lib/auth";
-import { hasCompletedOnboarding } from "./lib/onboarding";
 import { BugReportSection } from "./components/layout/BugReportSection";
 import { useApiHealth } from "./hooks/useApiHealth";
+import { IconSpark } from "./components/ui/icons";
 
 const ExploreView = lazy(() =>
   import("./views/ExploreView").then((m) => ({ default: m.ExploreView })),
@@ -102,7 +102,7 @@ function TopbarActions() {
         onClick={() => setAssistantOpen(true)}
         aria-label="Open Cortex Assist"
       >
-        ✦ Assist
+        <IconSpark size={16} aria-hidden /> Assist
       </button>
       <span
         className={`topbar__badge ${secured ? "topbar__badge--secured" : ""}`}
@@ -122,10 +122,8 @@ function TopbarActions() {
 }
 
 function AppChrome() {
-  const { setAssistantOpen } = useApp();
-  const [showOnboarding, setShowOnboarding] = useState(
-    () => typeof window !== "undefined" && !hasCompletedOnboarding(),
-  );
+  const { setAssistantOpen, setView, setWorkspaceId, showOnboarding, setShowOnboarding } =
+    useApp();
 
   return (
     <div className="app">
@@ -136,6 +134,10 @@ function AppChrome() {
         <OnboardingModal
           onComplete={() => setShowOnboarding(false)}
           onOpenCopilot={() => setAssistantOpen(true)}
+          onFinishAsk={(workspace, query) => {
+            setWorkspaceId(workspace);
+            setView("ask", { q: query });
+          }}
         />
       ) : null}
       <ApiHealthBanner />
diff --git a/frontend/src/components/layout/WorkspaceBar.tsx b/frontend/src/components/layout/WorkspaceBar.tsx
index eaacd06..98d8742 100644
--- a/frontend/src/components/layout/WorkspaceBar.tsx
+++ b/frontend/src/components/layout/WorkspaceBar.tsx
@@ -1,14 +1,14 @@
 import { useId, useState } from "react";
 import { useApp } from "../../context/AppContext";
 import { fetchHealth, hasApiKeyConfigured } from "../../api/client";
-import { persistApiKey } from "../../lib/auth";
-import { setClientApiKey } from "../../api/client";
 import { useToast } from "../ui/Toast";
+import { IconLock } from "../ui/icons";
 
 const PRESETS = ["local-dev", "acme-demo"] as const;
 
 export function WorkspaceBar() {
-  const { workspaceId, setWorkspaceId, apiKey, setApiKey, saveApiKey } = useApp();
+  const { workspaceId, setWorkspaceId, apiKey, setApiKey, saveApiKey, clearApiKey, replayOnboarding } =
+    useApp();
   const { showToast } = useToast();
   const [expanded, setExpanded] = useState(false);
   const [showKey, setShowKey] = useState(false);
@@ -44,8 +44,7 @@ export function WorkspaceBar() {
 
   function handleClear(): void {
     setApiKey("");
-    persistApiKey("");
-    setClientApiKey("");
+    clearApiKey();
     setTestOk(null);
     showToast("API key cleared");
   }
@@ -89,7 +88,7 @@ export function WorkspaceBar() {
             className={`connection-bar__status ${secured ? "connection-bar__status--secured" : ""}`}
             aria-hidden
           >
-            {secured ? "🔒" : "◇"}
+            {secured ? <IconLock size={14} /> : "◇"}
           </span>
           Connection
         </button>
@@ -139,6 +138,9 @@ export function WorkspaceBar() {
             >
               {testing ? "Testing…" : "Test connection"}
             </button>
+            <button type="button" className="btn btn--ghost" onClick={replayOnboarding}>
+              Replay tour
+            </button>
           </div>
           {secured ? (
             <p className="connection-bar__saved text-ok" role="status">
diff --git a/frontend/src/context/AppContext.tsx b/frontend/src/context/AppContext.tsx
index 359d57a..f36ef6a 100644
--- a/frontend/src/context/AppContext.tsx
+++ b/frontend/src/context/AppContext.tsx
@@ -12,11 +12,13 @@ import { WELCOME_MESSAGES, createMessage } from "../lib/assistant";
 import { loadStoredApiKey, persistApiKey } from "../lib/auth";
 import { setClientApiKey } from "../api/client";
 import { loadStoredWorkspace, persistWorkspace } from "../lib/workspace";
-import { viewFromHash, writeViewHash } from "../lib/routing";
+import { loadSettings, saveSettings } from "../lib/settings";
+import { parseHash, writeViewHash } from "../lib/routing";
+import { resetOnboarding } from "../lib/onboarding";
 
 type AppContextValue = {
   view: ViewId;
-  setView: (view: ViewId) => void;
+  setView: (view: ViewId, params?: { decision?: string; q?: string }) => void;
   workspaceId: string;
   setWorkspaceId: (id: string) => void;
   assistantOpen: boolean;
@@ -29,37 +31,68 @@ type AppContextValue = {
   setExploreDecisions: (decisions: DecisionResult[]) => void;
   selectedDecisionId: string | null;
   setSelectedDecisionId: (id: string | null) => void;
+  detailDecisionId: string | null;
+  setDetailDecisionId: (id: string | null) => void;
+  pendingAskQuery: string | null;
+  setPendingAskQuery: (q: string | null) => void;
   apiKey: string;
   setApiKey: (key: string) => void;
   saveApiKey: () => void;
+  clearApiKey: () => void;
+  showOnboarding: boolean;
+  setShowOnboarding: (open: boolean) => void;
+  replayOnboarding: () => void;
 };
 
 const AppContext = createContext<AppContextValue | null>(null);
 
+function initialWorkspace(): string {
+  if (typeof window === "undefined") return "local-dev";
+  return loadSettings().workspaceId || loadStoredWorkspace();
+}
+
 export function AppProvider({ children }: { children: ReactNode }) {
   const [view, setViewState] = useState<ViewId>(() =>
-    typeof window === "undefined" ? "home" : viewFromHash(),
-  );
-  const [workspaceId, setWorkspaceIdState] = useState(() =>
-    typeof window === "undefined" ? "local-dev" : loadStoredWorkspace(),
+    typeof window === "undefined" ? "home" : parseHash().view,
   );
+  const [workspaceId, setWorkspaceIdState] = useState(initialWorkspace);
   const [assistantOpen, setAssistantOpen] = useState(
     () => typeof window === "undefined" || window.innerWidth > 1100,
   );
   const [messages, setMessages] = useState<AssistantMessage[]>(WELCOME_MESSAGES);
   const [lastQuery, setLastQuery] = useState<QueryResponse | null>(null);
   const [exploreDecisions, setExploreDecisions] = useState<DecisionResult[]>([]);
-  const [selectedDecisionId, setSelectedDecisionId] = useState<string | null>(null);
+  const [selectedDecisionId, setSelectedDecisionId] = useState<string | null>(() =>
+    typeof window === "undefined" ? null : parseHash().decisionId ?? null,
+  );
+  const [detailDecisionId, setDetailDecisionId] = useState<string | null>(null);
+  const [pendingAskQuery, setPendingAskQuery] = useState<string | null>(() =>
+    typeof window === "undefined" ? null : parseHash().query ?? null,
+  );
   const [apiKey, setApiKeyState] = useState(() => loadStoredApiKey());
+  const [showOnboarding, setShowOnboarding] = useState(
+    () => typeof window !== "undefined" && !loadSettings().onboardingComplete,
+  );
 
-  const setView = useCallback((next: ViewId) => {
-    setViewState(next);
-    writeViewHash(next);
+  const replayOnboarding = useCallback(() => {
+    resetOnboarding();
+    setShowOnboarding(true);
   }, []);
 
+  const setView = useCallback(
+    (next: ViewId, params?: { decision?: string; q?: string }) => {
+      setViewState(next);
+      writeViewHash(next, params);
+      if (params?.decision) setSelectedDecisionId(params.decision);
+      if (params?.q) setPendingAskQuery(params.q);
+    },
+    [],
+  );
+
   const setWorkspaceId = useCallback((id: string) => {
     setWorkspaceIdState(id);
     persistWorkspace(id);
+    saveSettings({ workspaceId: id });
   }, []);
 
   const setApiKey = useCallback((key: string) => {
@@ -72,12 +105,23 @@ export function AppProvider({ children }: { children: ReactNode }) {
     setClientApiKey(apiKey);
   }, [apiKey]);
 
+  const clearApiKey = useCallback(() => {
+    setApiKeyState("");
+    persistApiKey("");
+    setClientApiKey("");
+  }, []);
+
   useEffect(() => {
     setClientApiKey(apiKey);
   }, [apiKey]);
 
   useEffect(() => {
-    const onHashChange = () => setViewState(viewFromHash());
+    const onHashChange = () => {
+      const route = parseHash();
+      setViewState(route.view);
+      if (route.decisionId) setSelectedDecisionId(route.decisionId);
+      if (route.query) setPendingAskQuery(route.query);
+    };
     window.addEventListener("hashchange", onHashChange);
     return () => window.removeEventListener("hashchange", onHashChange);
   }, []);
@@ -102,9 +146,17 @@ export function AppProvider({ children }: { children: ReactNode }) {
       setExploreDecisions,
       selectedDecisionId,
       setSelectedDecisionId,
+      detailDecisionId,
+      setDetailDecisionId,
+      pendingAskQuery,
+      setPendingAskQuery,
       apiKey,
       setApiKey,
       saveApiKey,
+      clearApiKey,
+      showOnboarding,
+      setShowOnboarding,
+      replayOnboarding,
     }),
     [
       view,
@@ -117,9 +169,14 @@ export function AppProvider({ children }: { children: ReactNode }) {
       lastQuery,
       exploreDecisions,
       selectedDecisionId,
+      detailDecisionId,
+      pendingAskQuery,
       apiKey,
       setApiKey,
       saveApiKey,
+      clearApiKey,
+      showOnboarding,
+      replayOnboarding,
     ],
   );
 
diff --git a/frontend/src/lib/routing.ts b/frontend/src/lib/routing.ts
index 4ab59bd..ff4ae26 100644
--- a/frontend/src/lib/routing.ts
+++ b/frontend/src/lib/routing.ts
@@ -2,13 +2,47 @@ import type { ViewId } from "../types";
 
 const VIEWS: ViewId[] = ["home", "ask", "explore", "agents", "review"];
 
+export type RouteParams = {
+  view: ViewId;
+  decisionId?: string;
+  query?: string;
+};
+
+export function parseHash(hash = window.location.hash): RouteParams {
+  const raw = hash.replace(/^#/, "");
+  const [path, queryString] = raw.split("?");
+  const viewRaw = path.split("/")[0];
+  const view = VIEWS.includes(viewRaw as ViewId) ? (viewRaw as ViewId) : "home";
+  const params = new URLSearchParams(queryString || "");
+  return {
+    view,
+    decisionId: params.get("decision") || undefined,
+    query: params.get("q") || undefined,
+  };
+}
+
 export function viewFromHash(hash = window.location.hash): ViewId {
-  const raw = hash.replace(/^#/, "").split("/")[0];
-  return VIEWS.includes(raw as ViewId) ? (raw as ViewId) : "home";
+  return parseHash(hash).view;
 }
 
-export function writeViewHash(view: ViewId): void {
-  if (window.location.hash.replace(/^#/, "").split("/")[0] !== view) {
-    window.location.hash = view;
+export function writeViewHash(view: ViewId, params?: { decision?: string; q?: string }): void {
+  const search = new URLSearchParams();
+  if (params?.decision) search.set("decision", params.decision);
+  if (params?.q) search.set("q", params.q);
+  const qs = search.toString();
+  const next = qs ? `${view}?${qs}` : view;
+  const current = window.location.hash.replace(/^#/, "");
+  if (current !== next) {
+    window.location.hash = next;
   }
 }
+
+export function buildDecisionShareUrl(decisionId: string): string {
+  const base = `${window.location.origin}${window.location.pathname}`;
+  return `${base}#/explore?decision=${encodeURIComponent(decisionId)}`;
+}
+
+export function buildAskShareUrl(query: string): string {
+  const base = `${window.location.origin}${window.location.pathname}`;
+  return `${base}#/ask?q=${encodeURIComponent(query)}`;
+}
diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
index e98e7b1..cf89dd8 100644
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -29,6 +29,7 @@ export type QueryResponse = {
   results: DecisionResult[];
   total: number;
   latency_ms: number;
+  coverage_score?: number;
 };
 
 export type InjectResponse = {