diff --git a/apps/web/src/components/app/docs-sections/agents.tsx b/apps/web/src/components/app/docs-sections/agents.tsx
index 9c517b3f..83d83e81 100644
--- a/apps/web/src/components/app/docs-sections/agents.tsx
+++ b/apps/web/src/components/app/docs-sections/agents.tsx
@@ -165,7 +165,7 @@ export function AgentsContent() {
- Quick Phrases
+ Quick Phrases
The Quick Phrases button (speech-bubble icon) in the
terminal top rail lets you save reusable text snippets and inject them
diff --git a/apps/web/src/components/app/docs-sections/primitives.tsx b/apps/web/src/components/app/docs-sections/primitives.tsx
index 8d1076a8..ba98caed 100644
--- a/apps/web/src/components/app/docs-sections/primitives.tsx
+++ b/apps/web/src/components/app/docs-sections/primitives.tsx
@@ -20,9 +20,17 @@ export function P({ children }: { children: React.ReactNode }) {
);
}
-export function H3({ children }: { children: React.ReactNode }) {
+export function H3({
+ id,
+ children,
+}: {
+ id?: string;
+ children: React.ReactNode;
+}) {
return (
-
{children}
+
+ {children}
+
);
}
diff --git a/apps/web/src/components/app/docs-sections/tools.tsx b/apps/web/src/components/app/docs-sections/tools.tsx
index b4947be3..73414c6d 100644
--- a/apps/web/src/components/app/docs-sections/tools.tsx
+++ b/apps/web/src/components/app/docs-sections/tools.tsx
@@ -214,7 +214,7 @@ export function ToolsContent() {
- Brain (shared memory)
+ Brain (shared memory)
The Brain is a repo-scoped key-value store and event log that lets
agents share structured state. Objects are organized into collections,
diff --git a/apps/web/src/components/app/notification-settings.tsx b/apps/web/src/components/app/notification-settings.tsx
index 95477843..6687425e 100644
--- a/apps/web/src/components/app/notification-settings.tsx
+++ b/apps/web/src/components/app/notification-settings.tsx
@@ -1,11 +1,17 @@
import { useCallback, useEffect, useRef, useState } from "react";
-import { useAtom } from "jotai";
-import { Play } from "lucide-react";
+import { useAtom, useSetAtom } from "jotai";
+import { Play, RotateCcw } from "lucide-react";
+import { toast } from "sonner";
import { Button } from "@/components/ui/button";
import { Checkbox } from "@/components/ui/checkbox";
import { Input } from "@/components/ui/input";
import { api } from "@/lib/api";
import { soundCuesEnabledAtom } from "@/lib/store";
+import {
+ dismissedTipsAtom,
+ lastSeenVersionAtom,
+ tipsEnabledAtom,
+} from "@/lib/tips/tips-state";
import { CUE_INTENTS, playCueForIntent, playTapCue } from "@/lib/sound-cues";
import {
getNotificationPermission,
@@ -91,6 +97,50 @@ function SoundCuesSection(): JSX.Element {
);
}
+function TipsSection(): JSX.Element {
+ const [enabled, setEnabled] = useAtom(tipsEnabledAtom);
+ const setDismissed = useSetAtom(dismissedTipsAtom);
+ const setLastSeenVersion = useSetAtom(lastSeenVersionAtom);
+
+ return (
+
+
+ Tips & Guidance
+
+
+ Contextual tips that highlight features and link to docs. This device
+ only.
+
+
+
+
+
+
+
+
+
+
{/* Browser Notifications */}
diff --git a/apps/web/src/components/tips/ambient-tip-bar.tsx b/apps/web/src/components/tips/ambient-tip-bar.tsx
new file mode 100644
index 00000000..0d067262
--- /dev/null
+++ b/apps/web/src/components/tips/ambient-tip-bar.tsx
@@ -0,0 +1,264 @@
+import { AnimatePresence, motion } from "framer-motion";
+import { Lightbulb } from "lucide-react";
+import { useAtomValue, useSetAtom } from "jotai";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useNavigate } from "react-router-dom";
+
+import { tips, type Tip } from "@/lib/tips/tips";
+import { dismissedTipsAtom, tipsEnabledAtom } from "@/lib/tips/tips-state";
+import { cn } from "@/lib/utils";
+
+const IDLE_DELAY_MS = 2.5 * 60 * 1000; // 2.5 minutes
+const SHOW_CHANCE = 0.4;
+const AUTO_HIDE_MS = 30_000;
+const ALL_SEEN_MS = 5_000;
+
+export function AmbientTipBar() {
+ const navigate = useNavigate();
+ const enabled = useAtomValue(tipsEnabledAtom);
+ const dismissed = useAtomValue(dismissedTipsAtom);
+ const setDismissed = useSetAtom(dismissedTipsAtom);
+ const setEnabled = useSetAtom(tipsEnabledAtom);
+
+ const [visibleTip, setVisibleTip] = useState(null);
+ const [allSeenMessage, setAllSeenMessage] = useState(false);
+ const shownThisSessionRef = useRef(new Set());
+ const hoveredRef = useRef(false);
+ const autoHideTimerRef = useRef>();
+ const idleTimerRef = useRef>();
+ const allSeenTimerRef = useRef>();
+
+ const getEligibleTip = useCallback((): Tip | null => {
+ const eligible = tips.filter(
+ (t) =>
+ t.surfaces.includes("ambient") &&
+ !dismissed.includes(t.id) &&
+ !shownThisSessionRef.current.has(t.id)
+ );
+ if (eligible.length === 0) return null;
+ return eligible[Math.floor(Math.random() * eligible.length)]!;
+ }, [dismissed]);
+
+ const startAutoHide = useCallback(() => {
+ clearTimeout(autoHideTimerRef.current);
+ autoHideTimerRef.current = setTimeout(() => {
+ if (!hoveredRef.current) {
+ setVisibleTip(null);
+ }
+ }, AUTO_HIDE_MS);
+ }, []);
+
+ const resetIdleTimer = useCallback(() => {
+ clearTimeout(idleTimerRef.current);
+ if (!enabled || visibleTip) return;
+
+ idleTimerRef.current = setTimeout(() => {
+ if (Math.random() > SHOW_CHANCE) {
+ resetIdleTimer();
+ return;
+ }
+ const tip = getEligibleTip();
+ if (tip) {
+ shownThisSessionRef.current.add(tip.id);
+ setVisibleTip(tip);
+ startAutoHide();
+ }
+ }, IDLE_DELAY_MS);
+ }, [enabled, visibleTip, getEligibleTip, startAutoHide]);
+
+ const lastResetRef = useRef(0);
+
+ useEffect(() => {
+ if (!enabled) {
+ setVisibleTip(null);
+ return;
+ }
+
+ const onActivity = () => {
+ if (visibleTip) return;
+ const now = Date.now();
+ if (now - lastResetRef.current < 10_000) return;
+ lastResetRef.current = now;
+ resetIdleTimer();
+ };
+
+ resetIdleTimer();
+ window.addEventListener("mousemove", onActivity);
+ window.addEventListener("keydown", onActivity);
+
+ return () => {
+ clearTimeout(idleTimerRef.current);
+ clearTimeout(autoHideTimerRef.current);
+ window.removeEventListener("mousemove", onActivity);
+ window.removeEventListener("keydown", onActivity);
+ };
+ }, [enabled, visibleTip, resetIdleTimer]);
+
+ const handleMouseEnter = useCallback(() => {
+ hoveredRef.current = true;
+ clearTimeout(autoHideTimerRef.current);
+ }, []);
+
+ const handleMouseLeave = useCallback(() => {
+ hoveredRef.current = false;
+ if (visibleTip) startAutoHide();
+ }, [visibleTip, startAutoHide]);
+
+ const handleDismiss = useCallback(() => {
+ if (visibleTip) {
+ setDismissed((prev) =>
+ prev.includes(visibleTip.id) ? prev : [...prev, visibleTip.id]
+ );
+ }
+ setVisibleTip(null);
+ clearTimeout(autoHideTimerRef.current);
+ resetIdleTimer();
+ }, [visibleTip, setDismissed, resetIdleTimer]);
+
+ const handleDisableAll = useCallback(() => {
+ setEnabled(false);
+ setVisibleTip(null);
+ setAllSeenMessage(false);
+ clearTimeout(autoHideTimerRef.current);
+ clearTimeout(allSeenTimerRef.current);
+ }, [setEnabled]);
+
+ const handleRequestTip = useCallback(() => {
+ if (visibleTip || allSeenMessage) return;
+ const eligible = tips.filter(
+ (t) => t.surfaces.includes("ambient") && !dismissed.includes(t.id)
+ );
+ if (eligible.length === 0) {
+ setAllSeenMessage(true);
+ clearTimeout(allSeenTimerRef.current);
+ allSeenTimerRef.current = setTimeout(
+ () => setAllSeenMessage(false),
+ ALL_SEEN_MS
+ );
+ return;
+ }
+ const tip = eligible[Math.floor(Math.random() * eligible.length)]!;
+ shownThisSessionRef.current.add(tip.id);
+ setVisibleTip(tip);
+ startAutoHide();
+ }, [visibleTip, allSeenMessage, dismissed, startAutoHide]);
+
+ useEffect(() => {
+ return () => clearTimeout(allSeenTimerRef.current);
+ }, []);
+
+ if (!enabled) return null;
+
+ const showBar = visibleTip || allSeenMessage;
+
+ return (
+
+ {/* 1: lightbulb — always in the same spot */}
+
+
+ {/* 2: tip text — grows, wraps */}
+
+ {visibleTip ? (
+
+
+ {visibleTip.title}
+
+ —
+ {visibleTip.body}
+ {visibleTip.docsSection ? (
+
+ ) : null}
+
+ ) : allSeenMessage ? (
+
+ Nothing left to teach you. You're a Dispatch natural.
+
+ ) : (
+
+ )}
+
+
+ {/* 3: actions — no wrap */}
+
+ {visibleTip ? (
+
+
+
+
+ ) : allSeenMessage ? (
+
+
+
+ ) : null}
+
+
+
+
+
+
+ {tip.title}
+
+
+
+
+
+ {tip.body}
+
+
+ {tip.docsSection ? (
+
+ ) : (
+
+ )}
+
+
+