From dc3e8a0e811e36303959e2b41a76eadb828cf83b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Gurruchaga?= <jsgrrchg@gmail.com>
Date: Thu, 21 May 2026 12:40:20 -0400
Subject: [PATCH 1/2] Add keyboard shortcut hints to empty pane placeholder
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The empty pane placeholder now lists each action alongside its keyboard
shortcut, resolved from the shortcut registry at render time so hints stay
accurate after rebinds and use the correct platform modifier (⌘ vs Ctrl).

Closes #119
---
 .../editor/WorkspacePaneEmptyState.test.tsx   | 25 +++++++++++---
 .../editor/WorkspacePaneEmptyState.tsx        | 34 +++++++++++++++++--
 2 files changed, 52 insertions(+), 7 deletions(-)

diff --git a/apps/desktop/src/features/editor/WorkspacePaneEmptyState.test.tsx b/apps/desktop/src/features/editor/WorkspacePaneEmptyState.test.tsx
index c054fcc4..37541f8c 100644
--- a/apps/desktop/src/features/editor/WorkspacePaneEmptyState.test.tsx
+++ b/apps/desktop/src/features/editor/WorkspacePaneEmptyState.test.tsx
@@ -19,12 +19,27 @@ describe("WorkspacePaneEmptyState", () => {
         );
     });
 
-    it("shows a compact empty state message", () => {
-        renderComponent(<WorkspacePaneEmptyState paneId="primary" />);
+    it("shows a compact empty state message with shortcut hints", () => {
+        const { container } = renderComponent(
+            <WorkspacePaneEmptyState paneId="primary" />,
+        );
+
+        // The placeholder lists each action with its keyboard shortcut.
+        // Text nodes are interleaved with <kbd> elements, so assert on the
+        // paragraph's combined text content.
+        const text = container.textContent ?? "";
+        expect(text).toContain("Open a file");
+        expect(text).toContain("browse commands");
+        expect(text).toContain("start a chat");
+        expect(text).toContain("launch a terminal");
+
+        // Shortcuts are resolved from the registry for the macOS test platform.
+        const hints = Array.from(
+            container.querySelectorAll("kbd"),
+            (kbd) => kbd.textContent,
+        );
+        expect(hints).toEqual(["⌘O", "⌘K", "⌘⇧N", "⌘R"]);
 
-        expect(
-            screen.getByText("Open a file, start a chat or launch a terminal."),
-        ).toBeVisible();
         expect(
             screen.queryByRole("button", { name: "New Note" }),
         ).not.toBeInTheDocument();
diff --git a/apps/desktop/src/features/editor/WorkspacePaneEmptyState.tsx b/apps/desktop/src/features/editor/WorkspacePaneEmptyState.tsx
index 0b35935d..d638f754 100644
--- a/apps/desktop/src/features/editor/WorkspacePaneEmptyState.tsx
+++ b/apps/desktop/src/features/editor/WorkspacePaneEmptyState.tsx
@@ -1,7 +1,33 @@
+import { formatShortcutAction } from "../../app/shortcuts/format";
+import type { ShortcutActionId } from "../../app/shortcuts/registry";
+import { getDesktopPlatform } from "../../app/utils/platform";
+
 interface WorkspacePaneEmptyStateProps {
     paneId: string;
 }
 
+// Resolve the binding from the shortcut registry at render time so the hint
+// stays accurate if the user rebinds an action, and so the platform modifier
+// (⌘ vs Ctrl) is correct per OS.
+function ShortcutHint({ action }: { action: ShortcutActionId }) {
+    const label = formatShortcutAction(action, getDesktopPlatform());
+    if (!label) return null;
+    return (
+        <kbd
+            className="ml-1 rounded px-1.5 py-0.5 text-xs font-medium"
+            style={{
+                color: "var(--text-primary)",
+                background: "var(--bg-tertiary)",
+                border: "1px solid color-mix(in srgb, var(--border) 80%, transparent)",
+                fontFamily: "inherit",
+                whiteSpace: "nowrap",
+            }}
+        >
+            {label}
+        </kbd>
+    );
+}
+
 export function WorkspacePaneEmptyState({
     paneId,
 }: WorkspacePaneEmptyStateProps) {
@@ -11,10 +37,14 @@ export function WorkspacePaneEmptyState({
             data-workspace-empty-pane={paneId}
         >
             <p
-                className="max-w-md text-center text-sm leading-6"
+                className="max-w-md text-center text-sm leading-8"
                 style={{ color: "var(--text-secondary)" }}
             >
-                Open a file, start a chat or launch a terminal.
+                Open a file
+                <ShortcutHint action="quick_switcher" />, browse commands
+                <ShortcutHint action="command_palette" />, start a chat
+                <ShortcutHint action="new_agent" />, or launch a terminal
+                <ShortcutHint action="new_terminal" />.
             </p>
         </div>
     );

From c42743b0123f64c398188d3fd111ec3db6684c7f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Gurruchaga?= <jsgrrchg@gmail.com>
Date: Thu, 21 May 2026 12:47:50 -0400
Subject: [PATCH 2/2] Fix empty pane shortcut hint test on Linux

---
 .../features/editor/WorkspacePaneEmptyState.test.tsx | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/apps/desktop/src/features/editor/WorkspacePaneEmptyState.test.tsx b/apps/desktop/src/features/editor/WorkspacePaneEmptyState.test.tsx
index 37541f8c..3527aa09 100644
--- a/apps/desktop/src/features/editor/WorkspacePaneEmptyState.test.tsx
+++ b/apps/desktop/src/features/editor/WorkspacePaneEmptyState.test.tsx
@@ -1,7 +1,9 @@
 import "@testing-library/jest-dom/vitest";
 import { screen } from "@testing-library/react";
 import { beforeEach, describe, expect, it } from "vitest";
+import { formatShortcutAction } from "../../app/shortcuts/format";
 import { useEditorStore } from "../../app/store/editorStore";
+import { getDesktopPlatform } from "../../app/utils/platform";
 import { renderComponent } from "../../test/test-utils";
 import { WorkspacePaneEmptyState } from "./WorkspacePaneEmptyState";
 
@@ -33,12 +35,18 @@ describe("WorkspacePaneEmptyState", () => {
         expect(text).toContain("start a chat");
         expect(text).toContain("launch a terminal");
 
-        // Shortcuts are resolved from the registry for the macOS test platform.
+        // Shortcuts are resolved from the registry for the current test platform.
         const hints = Array.from(
             container.querySelectorAll("kbd"),
             (kbd) => kbd.textContent,
         );
-        expect(hints).toEqual(["⌘O", "⌘K", "⌘⇧N", "⌘R"]);
+        const platform = getDesktopPlatform();
+        expect(hints).toEqual([
+            formatShortcutAction("quick_switcher", platform),
+            formatShortcutAction("command_palette", platform),
+            formatShortcutAction("new_agent", platform),
+            formatShortcutAction("new_terminal", platform),
+        ]);
 
         expect(
             screen.queryByRole("button", { name: "New Note" }),