From 568207687da91ae7c339da2061017e9c542c60ae Mon Sep 17 00:00:00 2001
From: Dave <futurechimp@users.noreply.github.com>
Date: Sat, 14 Mar 2026 18:53:29 +0000
Subject: [PATCH] story-kit: merge 241_story_help_slash_command

---
 frontend/src/components/Chat.tsx        |  10 ++
 frontend/src/components/HelpOverlay.tsx | 158 ++++++++++++++++++++++++
 2 files changed, 168 insertions(+)
 create mode 100644 frontend/src/components/HelpOverlay.tsx

diff --git a/frontend/src/components/Chat.tsx b/frontend/src/components/Chat.tsx
index 1ad976c..1368ec9 100644
--- a/frontend/src/components/Chat.tsx
+++ b/frontend/src/components/Chat.tsx
@@ -10,6 +10,7 @@ import { AgentPanel } from "./AgentPanel";
 import { ChatHeader } from "./ChatHeader";
 import type { ChatInputHandle } from "./ChatInput";
 import { ChatInput } from "./ChatInput";
+import { HelpOverlay } from "./HelpOverlay";
 import { LozengeFlyProvider } from "./LozengeFlyContext";
 import { MessageItem } from "./MessageItem";
 import { SideQuestionOverlay } from "./SideQuestionOverlay";
@@ -203,6 +204,7 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 		response: string;
 		loading: boolean;
 	} | null>(null);
+	const [showHelp, setShowHelp] = useState(false);
 	// Ref so stale WebSocket callbacks can read the current queued messages
 	const queuedMessagesRef = useRef<{ id: string; text: string }[]>([]);
 	const queueIdCounterRef = useRef(0);
@@ -475,6 +477,12 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 	const sendMessage = async (messageText: string) => {
 		if (!messageText.trim()) return;
 
+		// /help — show available slash commands overlay
+		if (/^\/help\s*$/i.test(messageText)) {
+			setShowHelp(true);
+			return;
+		}
+
 		// /btw <question> — answered from context without disrupting main chat
 		const btwMatch = messageText.match(/^\/btw\s+(.+)/s);
 		if (btwMatch) {
@@ -1193,6 +1201,8 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 				</div>
 			)}
 
+			{showHelp && <HelpOverlay onDismiss={() => setShowHelp(false)} />}
+
 			{sideQuestion && (
 				<SideQuestionOverlay
 					question={sideQuestion.question}
diff --git a/frontend/src/components/HelpOverlay.tsx b/frontend/src/components/HelpOverlay.tsx
new file mode 100644
index 0000000..0f6a3e2
--- /dev/null
+++ b/frontend/src/components/HelpOverlay.tsx
@@ -0,0 +1,158 @@
+import * as React from "react";
+
+const { useEffect, useRef } = React;
+
+interface SlashCommand {
+	name: string;
+	description: string;
+}
+
+const SLASH_COMMANDS: SlashCommand[] = [
+	{
+		name: "/help",
+		description: "Show this list of available slash commands.",
+	},
+	{
+		name: "/btw <question>",
+		description:
+			"Ask a side question using the current conversation as context. The question and answer are not added to the conversation history.",
+	},
+];
+
+interface HelpOverlayProps {
+	onDismiss: () => void;
+}
+
+/**
+ * Dismissible overlay that lists all available slash commands.
+ * Dismiss with Escape, Enter, or Space.
+ */
+export function HelpOverlay({ onDismiss }: HelpOverlayProps) {
+	const dismissRef = useRef(onDismiss);
+	dismissRef.current = onDismiss;
+
+	useEffect(() => {
+		const handler = (e: KeyboardEvent) => {
+			if (e.key === "Escape" || e.key === "Enter" || e.key === " ") {
+				e.preventDefault();
+				dismissRef.current();
+			}
+		};
+		window.addEventListener("keydown", handler);
+		return () => window.removeEventListener("keydown", handler);
+	}, []);
+
+	return (
+		// biome-ignore lint/a11y/noStaticElementInteractions: backdrop dismiss is supplementary; keyboard handled via window keydown
+		// biome-ignore lint/a11y/useKeyWithClickEvents: keyboard dismiss handled via window keydown listener
+		<div
+			data-testid="help-overlay"
+			onClick={onDismiss}
+			style={{
+				position: "fixed",
+				inset: 0,
+				background: "rgba(0,0,0,0.55)",
+				display: "flex",
+				alignItems: "center",
+				justifyContent: "center",
+				zIndex: 1000,
+			}}
+		>
+			{/* biome-ignore lint/a11y/useKeyWithClickEvents: stop-propagation only; no real interaction */}
+			{/* biome-ignore lint/a11y/noStaticElementInteractions: stop-propagation only; no real interaction */}
+			<div
+				data-testid="help-panel"
+				onClick={(e) => e.stopPropagation()}
+				style={{
+					background: "#2f2f2f",
+					border: "1px solid #444",
+					borderRadius: "12px",
+					padding: "24px",
+					maxWidth: "560px",
+					width: "90vw",
+					display: "flex",
+					flexDirection: "column",
+					gap: "16px",
+					boxShadow: "0 8px 32px rgba(0,0,0,0.5)",
+				}}
+			>
+				{/* Header */}
+				<div
+					style={{
+						display: "flex",
+						alignItems: "center",
+						justifyContent: "space-between",
+					}}
+				>
+					<span
+						style={{
+							fontSize: "0.7rem",
+							fontWeight: 700,
+							letterSpacing: "0.08em",
+							textTransform: "uppercase",
+							color: "#a0d4a0",
+						}}
+					>
+						Slash Commands
+					</span>
+					<button
+						type="button"
+						onClick={onDismiss}
+						title="Dismiss (Escape, Enter, or Space)"
+						style={{
+							background: "none",
+							border: "none",
+							color: "#666",
+							cursor: "pointer",
+							fontSize: "1.1rem",
+							padding: "2px 6px",
+							borderRadius: "4px",
+						}}
+					>
+						✕
+					</button>
+				</div>
+
+				{/* Command list */}
+				<div style={{ display: "flex", flexDirection: "column", gap: "12px" }}>
+					{SLASH_COMMANDS.map((cmd) => (
+						<div
+							key={cmd.name}
+							style={{ display: "flex", flexDirection: "column", gap: "2px" }}
+						>
+							<code
+								style={{
+									fontSize: "0.88rem",
+									color: "#e0e0e0",
+									fontFamily: "monospace",
+								}}
+							>
+								{cmd.name}
+							</code>
+							<span
+								style={{
+									fontSize: "0.85rem",
+									color: "#999",
+									lineHeight: "1.5",
+								}}
+							>
+								{cmd.description}
+							</span>
+						</div>
+					))}
+				</div>
+
+				{/* Footer hint */}
+				<div
+					style={{
+						fontSize: "0.75rem",
+						color: "#555",
+						textAlign: "center",
+					}}
+				>
+					Press Escape, Enter, or Space to dismiss
+				</div>
+			</div>
+		</div>
+	);
+}